Tuanzi's Server Mod (团子服务器增强模组)

基于 Minecraft 26.1 (1.22) Fabric 开发的服务器端全能增强模组，集成了高级身份验证、多币种经济、智能商店、称号系统、CDK 礼包码、Warp 地标传送及全维度玩家统计系统。无需客户端安装模组即可使用。

核心特性

1. 商店系统 (Smart Shop)

• 引导式创建：右键点击空木牌即可开启交互式引导，支持聊天框按钮选择和数字输入。
• 分类型动态定价：
  • 收购模式 (BUY): $P = x + (y - x) \cdot \frac{K}{K + S}$ (价格随收购量增加而回归保底价 $x$)
  • 出售模式 (SELL): $P = x + (y - x) \cdot \frac{S}{K + S}$ (价格随销售量增加而上升)
• 视觉展示：基于 ItemEntity 的悬浮物品展示，具备防吸取、物理静止及非持久化特性（重启自动恢复）。
• 多维度支持：支持在主世界、下界和末地创建并自动维护商店（定时衰减与展示自适应当前维度，支持旧商店维度自愈扫描）。
• 安全与体验：集成漏斗防护（防止通过漏斗或漏斗矿车窃取），以及背包满时购买物品自动安全掉落机制（绝不吞物）。

2. 经济系统 (Advanced Economy)

• 多钱包架构：支持管理员自定义多种货币（如金币、点券）。
• 动态翻译：货币名称及交易反馈完全适配玩家客户端语言。
• 离线交易：支持玩家向离线玩家转账（需已注册）。
• 多开防刷限制：支持开启同 IP 转账检测（allowSameIPTransfer），防范小号刷钱。支持配置热重载（/econ-admin config reload）。

3. 身份验证与假人联动 (Mixed Auth & Carpet Bot)

• 正盗版混合验证：自动识别 Mojang 正版账户并免密登录；盗版玩家需注册登录。
• 安全防护：登录前禁止所有物理和交互操作，防止位置信息泄露和非法破坏。
• Carpet 假人免密登录：自动识别并置假人为已登录状态，方便假人在后台流畅运作。
• 假人防盗安全拦截：正版真人首次登录自动记录至 premium_players.json。假人生成时进行“已注册”和“正版真人登录历史”二阶段校验，严防恶意生成假人免密登录盗取玩家背包物资。
• 白名单管理：集成 UUID 映射的增强白名单系统。

4. Warp 地标系统 (Warp System)

• 高效传送：允许玩家使用 /warp <地标名> 在不同地标传送，支持 /warpback 回传至前一次传送点（跨维度精准支持）。
• 安全机制：传送需原地站立等待 3 秒，若期间移动或受到伤害将被自动打断。
• 管理员地标库：支持管理员创建（/warpadmin create，支持 ~ ~ ~ 相对坐标）、删除及列表查询，数据自动持久化。

5. 称号系统 (Title System)

• 多处展示：称号同步显示在聊天栏前缀、Tab 玩家列表及玩家头顶名称上方。
• 颜色优化：支持 & 彩色代码，特殊渲染优化防止颜色溢出到用户名。
• 激活方式：支持管理员直接发放或通过特殊的“称号命名牌”由玩家自行激活。
• 限时与赛季管理：支持限时命名牌（激活叠加时长）及全局到期时间设置，到期自动卸下、定时清理并发送离线/在线通知。
• 离线兼容：支持为离线玩家发放称号，玩家上线后将自动收到通知。

6. CDK 礼包码系统 (CDK System)

• 后台指令执行：玩家兑换时由控制台代执行指令，无需提升玩家权限即可发放复杂奖励。
• 多维度限制：
  • 类型丰富：支持全局一次性、玩家一次性、全服限量单人一次（GLOBAL_LIMIT）及个人限量（PLAYER_LIMIT）。
  • 时效管理：可设置精确到秒的过期时间，支持 yyyy-MM-dd 及 "yyyy-MM-dd HH:mm:ss" 格式设置。
• 批量生成与导出：支持基于模板批量生成随机代码，并可导出为 CSV、JSON 或 TXT 格式。
• 详尽审计：独立记录所有兑换流水，包含时间、指令快照及玩家信息。

7. 统计系统 (Total Stats)

• 全方位指标：记录移动距离、击杀、挖掘、在线时间、称号持有量、CDK 兑换数等 25+ 项指标，针对假人/非正常断线离线玩家进行了在线时间累加修正。
• 实时排行榜：支持侧边栏计分板自动轮换和悬浮文字动态展示。
• 数据导出：支持统计数据的一键导出与重置。

8. 备份回滚与数据安全 (Backup & IO Safety)

• 自动化备份：支持按小时自动打包所有核心数据。存储于 ./mod_backups/。
• 安全恢复：一键回滚至指定时间点，含聊天框确认和 pre_restore 强制定时快照备份，恢复后自动停机。
• 防断电 IO 保护：所有本地数据读写引入“备份回滚 (.bak) + 临时文件原子替换 (.tmp)”双重保护，彻底防范断电/崩溃引起的文件损坏或清空。

指令索引

玩家常用指令

指令	描述	备注
/login <密码>	账户登录	正版玩家免密
/register <密码> <确认密码>	账户注册	仅需一次
/pay <玩家> <货币ID> <数量>	转账金币	支持货币 ID 补全
/balance [货币ID]	查询余额	缺省显示所有钱包
/stats [player] [type]	查看个人或他人统计	支持 25+ 种子项
/titles <list/set/clear>	称号管理	查看、佩戴或卸下称号（支持查看有效期）
/cdk <代码>	兑换礼包码	成功后自动执行奖励指令
/warp <地标名>	传送至指定地标	原地站立等待 3 秒，受伤或移动打断
/warpback	返回传送前的位置	跨维度支持
/shop help	商店功能指南	包含买/卖操作说明

管理员指令 (Level 4)

指令	描述	备注
/auth whitelist <add/remove/list>	白名单管理	支持 UUID 自动生成
/econ-admin balance <set/add/remove>	管理玩家余额	全货币支持
/econ-admin config reload	重新加载经济模块配置	不重启动态生效
/econ-admin config set allowSameIPTransfer <true/false>	开启/关闭同 IP 转账检测	防止小号/多开刷钱
/eco backup	执行全量备份	存储于 ./mod_backups/
/eco restore <timestamp>	恢复指定备份	含有确认流程，自动强制定时快照，恢复后关闭服务器
/eco interval <hours>	设置备份周期	默认为 12 小时
/warpadmin create <地标名> <x> <y> <z>	创建新地标	支持 ~ 相对坐标
/warpadmin delete <地标名>	删除指定地标
/warpadmin list	列出所有地标
/titleadmin <create/delete/give/getitem>	称号库管理	现支持 [days] 时间参数
/titleadmin setexpiry <id> <date>	称号全局过期设置	设置全服称号的结束时间
/titleadmin modifyplayer <targets> <id> <set/add/remove> <days>	玩家称号时间管理	设定/延长/缩短玩家持有时间
/cdkadmin <create/batch/list/export>	CDK 系统管理	支持批量生成与历史导出
/cdkadmin setexpiry <id> <date>	CDK 过期时间管理	支持 yyyy-MM-dd 或 "yyyy-MM-dd HH:mm:ss" 格式
/shopadmin info	查看商店调试数据	展示 S, K, 衰减率等
/shopadmin setupDynamic	开启引导式动态定价设置	分三步设置核心变量
/scoreboard <start/stop/interval>	计分板轮换控制	支持动态调整速度
/floatingtext <create/delete/set>	悬浮文字排行榜管理	支持颜色和位置调整

技术规格

• 平台: Minecraft 26.1 (1.22) Fabric
• Java 版本: Java 25 (推荐 Zulu-25)
• 性能与调试:
  • 商店展示采用 5-tick 节流维护。
  • 统计数据采用异步保存机制。
  • 展示实体采用非持久化方案，零存档负担。
  • 集成统一全局调试日志系统 (TuanzisServerMod.debug)，生产环境默认静默，避免刷屏。

国际化 (i18n)

本模组完全支持中英双语。系统会根据玩家在 Minecraft 客户端设置的语言自动切换：

• 中文 (简体): zh_cn (含 zh_tw, zh_hk 自动规范化)
• English: en_us (默认兜底)

---

English Version

Tuanzi's Server Mod

A comprehensive server-side enhancement mod developed for Minecraft 26.1 (1.22) Fabric, integrating advanced authentication, multi-currency economy, smart shops, title system, CDK gift codes, Warp landmark teleportation, and an all-dimensional player statistics system. No client-side mod required.

Core Features

1. Smart Shop System

• Guided Creation: Right-click an empty sign to start an interactive guide with chat button selection and numerical input.
• Typed Dynamic Pricing:
  • BUY Mode (Purchasing): $P = x + (y - x) \cdot \frac{K}{K + S}$ (Price converges to floor $x$ as stock increases)
  • SELL Mode (Selling): %P = x + (y - x) \cdot \frac{S}{K + S}% (Price rises as sales volume increases)
• Visual Display: ItemEntity-based floating item displays with anti-pickup, physical stillness, and non-persistence features (auto-restored on reboot).
• Multi-Dimension Support: Create and maintain shops in the Overworld, Nether, and End automatically. Supports multi-dimension display management without dimensional collision, auto-adaptive decay updates, and self-healing scanning for old shops.
• Security & Protection: Integrated hopper protection preventing illegal extraction via hoppers or hopper minecarts.
• Overflow Drop: Safely drops overflow items at the player's feet when buying with a full inventory, preventing item loss.

2. Advanced Economy

• Multi-Wallet Architecture: Supports custom currencies (e.g., Gold, Credits).
• Dynamic Translation: Currency names and transaction feedback fully adapt to the player's client language.
• Offline Transactions: Supports transfers to registered offline players.
• Same IP Transfer Detection: Added allowSameIPTransfer setting to detect/prevent transfers between players on the same IP to combat alt-account abuse. Supports config hot reloading (/econ-admin config reload).

3. Mixed Authentication & Carpet Bot Integration

• Mixed Verification: Automatically identifies Mojang premium accounts for password-less login; offline players must register.
• Security Sandbox: Restricts all physical and interactive operations before login to prevent information leaks or unauthorized damage.
• Carpet Bot Auto-Login: Automatically identifies and logs in Carpet fake players (carpet.patches.EntityPlayerMPFake), allowing seamless background operations.
• Carpet Bot Security Restriction: Persists premium players' login history into premium_players.json. Implements a two-stage verification (registered check and premium history check) when spawning a bot via /player to block malicious password-less bot spawns stealing player inventories.
• Whitelist Management: Enhanced whitelist system integrated with UUID mapping.

4. Warp Landmark System

• Efficient Teleportation: Allows players to use /warp <name> to teleport to established landmarks, and /warpback to return to the location before teleport (fully supports cross-dimension).
• Safety Lock: Requires players to stand still for 3 seconds; movement or taking damage will interrupt teleportation.
• Landmark Management: Admins can create (supporting ~ ~ ~ relative coordinates), delete, and list landmarks with automatic data persistence.

5. Title System

• Multi-location Display: Titles are synchronized in the chat prefix, Tab player list, and above the player's head.
• Color Optimization: Supports & color codes with special rendering optimization to prevent color bleeding to the username.
• Activation Methods: Supports direct issuance by administrators or activation via special "Title Name Tags" by players.
• Expiry & Season Management: Supports temporary titles, global title expiry dates, cumulative duration for multiple activations, real-time hover expiry check, and automatic background cleanup with alerts.
• Offline Compatibility: Supports issuing titles to offline players, who will automatically receive a notification upon logging in.

6. CDK System (Gift Codes)

• Backend Command Execution: Commands are executed by the console upon redemption, allowing for complex rewards without elevating player permissions.
• Multi-dimensional Restrictions:
  • Types: Supports global one-time, player one-time, global limit with single redemption (GLOBAL_LIMIT), and player-specific limit (PLAYER_LIMIT).
  • Expiration Management: Set precise expiration dates down to the second, supporting yyyy-MM-dd and "yyyy-MM-dd HH:mm:ss" formats.
• Batch Generation & Export: Supports batch generation of random codes based on templates and exporting to CSV, JSON, or TXT formats.
• Detailed Auditing: Independently records all redemption history, including timestamps, command snapshots, and player info.

7. Total Statistics System

• All-round Metrics: Records 25+ metrics including distance traveled, kills, mining, online time, title ownership, CDK redemptions, etc. Fixes the issue where Carpet bots or abruptly disconnected offline players continued accumulating online time.
• Real-time Leaderboards: Supports automatic sidebar scoreboard rotation and dynamic floating text displays.
• Data Export: Supports one-click exporting and resetting of statistical data.

8. Backup, Recovery & Data Safety

• Automated Backups: Periodically packages all core data (Economy, Shop, Stats, CDK, Titles, Whitelist) into ./mod_backups/.
• Secure Recovery: One-click rollback to a specific timestamp, incorporating double confirmation, automatic emergency pre-restore backup, followed by a safe shutdown.
• Anti-Power-Loss IO Protection: Local data and configurations are protected by a double mechanism: Backup Rollback (.bak) + Temporary File Atomic Replacement (.tmp), entirely preventing corruption or truncation due to sudden crashes.

Command Index

Common Player Commands

Command	Description	Note
/login <password>	Account login	Auto-login for Premium
/register <pass> <confirm>	Account registration	Required only once
/pay <player> <walletId> <qty>	Transfer currency	Tab-completion supported
/balance [walletId]	Check balances	Shows all wallets by default
/stats [player] [type]	View player stats	Supports 25+ metrics
/titles <list/set/clear>	Title management	View, wear, or remove titles (with expiry display)
/cdk <code>	Redeem gift code	Executes reward commands on success
/warp <name>	Teleport to a landmark	Stand still for 3 seconds, interrupted by movement/damage
/warpback	Return to previous location	Cross-dimension supported
/shop help	Shop functionality guide	Includes Buy/Sell instructions

Admin Commands (Level 4)

Command	Description	Note
/auth whitelist <add/remove/list>	Whitelist management	Supports UUID generation
/econ-admin balance <set/add/rem>	Manage player balances	Multi-currency support
/econ-admin config reload	Reload economy config	Applies dynamically
/econ-admin config set allowSameIPTransfer <true/false>	Toggle same IP transfer check	Prevents alt-account abuse
/eco backup	Perform full backup	Stored in ./mod_backups/
/eco restore <timestamp>	Restore from backup	Double confirmation, pre-restore backup, stops server
/eco interval <hours>	Set backup interval	Default is 12 hours
/warpadmin create <name> <x> <y> <z>	Create a landmark	Supports ~ relative coordinates
/warpadmin delete <name>	Delete a landmark
/warpadmin list	List all landmarks
/titleadmin <create/delete/give/getitem>	Title repository	Supports [days] duration parameter
/titleadmin setexpiry <id> <date>	Global title expiry	Set end date for a title for all players
/titleadmin modifyplayer <targets> <id> <set/add/rem> <days>	Player title duration	Set/extend/shorten holding time
/cdkadmin <create/batch/list/export>	CDK management	Batch generation and history export
/cdkadmin setexpiry <id> <date>	CDK expiry date	Supports yyyy-MM-dd or "yyyy-MM-dd HH:mm:ss"
/shopadmin info	Shop debug data	Shows S, K, Decay rate, etc.
/shopadmin setupDynamic	Guided dynamic pricing setup	3-step core variable setup
/scoreboard <start/stop/interval>	Scoreboard rotation control	Adjust rotation speed
/floatingtext <create/delete/set>	Floating text leaderboards	Color and position adjustment

Technical Specifications

• Platform: Minecraft 26.1 (1.22) Fabric
• Java Version: Java 25 (Zulu-25 recommended)
• Performance & Logging:
  • Shop displays maintained using a 5-tick throttle.
  • Statistics data saved using an asynchronous mechanism.
  • Display entities use a non-persistent scheme, zero save bloat.
  • Integrated unified global debug log system (TuanzisServerMod.debug), silent by default in production.

Internationalization (i18n)

This mod fully supports English and Chinese. The system automatically switches based on the player's client language:

• Chinese: zh_cn (Includes automatic normalization for zh_tw, zh_hk)
• English: en_us (Default fallback)