玩家地毯扩展

🎮 Player Carpet Extension (PlayerCarpetEx)

一个强大的 Carpet 模组扩展，让服务器管理员完全掌控玩家物品栏。

---

📖 概述

Player Carpet Extension 是一个服务端 Fabric 模组，通过先进的玩家物品栏管理工具扩展了 Carpet Mod 的功能。专为服务器管理员、SMP 管理员和地图制作者设计，该模组提供了两个核心功能，彻底改变你在服务器上与玩家物品栏交互的方式。

该模组能做什么？

该模组为你的 Minecraft 服务器增加了两大系统：

1. 远程物品栏查看与管理 — 以完整 GUI 界面打开任意玩家的物品栏，并支持双向同步。你在查看器中所做的任何更改都会立即应用到目标玩家的物品栏，反之亦然。你还可以使用命令在任意玩家的物品栏格子中给予、移除、交换、设置、计数、压缩和丢弃物品。

2. 自动切换快捷栏系统 — 当所选快捷栏物品用尽时自动补充。系统从下一个可用快捷栏格子拉取物品，如果整个快捷栏为空，则从主物品栏拉取。当所有物品耗尽时，主物品栏将被锁定，以防止外部修改，直到有新物品提供。

---

✨ 功能

🎯 物品栏 GUI 查看器

直接在游戏客户端中打开任意玩家物品栏的视觉化表示。查看器显示一个 54 格（9×6）的容器，其精心布局的结构镜像了玩家实际物品栏的结构。

GUI 布局结构：

容器视图被分为使用装饰性玻璃板清晰标记的部分：

行	格子	内容	描述
第 0 行	0–8	副手 + 护甲 + 玻璃	格子 0 = 副手，格子 2 = 头盔，格子 3 = 胸甲，格子 4 = 护腿，格子 5 = 靴子。蓝色玻璃板填充装饰位置（格子 1、6、7、8）。
第 1 行	9–17	快捷栏	玩家快捷栏格子 1 到 9，按顺序显示。
第 2 行	18–26	分隔符	灰色玻璃板在快捷栏/护甲区域和主物品栏之间创建视觉分隔。
第 3 行	27–35	主物品栏（第一行）	主物品栏格子 9–17。
第 4 行	36–44	主物品栏（第二行）	主物品栏格子 18–26。
第 5 行	45–53	主物品栏（第三行）	主物品栏格子 27–35。

双向同步：

• 查看器物品栏每 10 刻（0.5 秒）与目标玩家物品栏同步，确保即使目标玩家移动物品，你也能始终看到最新状态。
• 当你在查看器中修改物品（拾取、放置、交换）时，这些更改会立即推送到目标玩家的物品栏。
• 一个 syncing 标志可防止在初始化和修改期间出现无限重入同步循环。
• 在初始化期间强制执行玻璃板分隔符，并在同步过程中保留。

🔄 自动切换快捷栏

自动切换系统持续监控玩家选中的快捷栏格子，并在其变空时自动补充。这非常适合自动化农场、PvP 服务器或任何需要玩家持续供应物品的场景。

自动切换逻辑的工作原理：

1. 快捷栏检查 — 当选中的快捷栏格子为空时，系统扫描剩余的快捷栏格子（循环）以寻找最近的可用物品。如果找到，它会将该物品移动到选中的格子并通知玩家。
2. 从物品栏拉取 — 如果整个快捷栏为空，系统搜索主物品栏（格子 9–35）中的任何物品，并将其拉到当前选中的快捷栏格子。
3. 物品栏锁定 — 当所有快捷栏和主物品栏格子完全为空时，系统锁定主物品栏。锁定后，外部向主物品栏添加物品的尝试（来自发射器、漏斗或其他机制）将被阻止。物品只能添加到快捷栏。
4. 自动解锁 — 如果在锁定的物品栏中检测到物品，锁会自动解除，恢复正常操作。

---

📦 安装

要求

依赖项	最低版本	用途
Minecraft	1.20.4	目标游戏版本
Fabric Loader	0.15.0+	模组加载器
Fabric API	最新 1.20.4 版本	API 框架
Carpet Mod	1.4.128+	必需的父模组
Java	17+	运行时环境

步骤

1. 安装 Fabric Loader — 下载并安装适用于 Minecraft 1.20.4 的 Fabric Loader。
2. 安装 Fabric API — 下载适用于 Minecraft 1.20.4 的 Fabric API 并将其放入你的 mods/ 文件夹。
3. 安装 Carpet Mod — 下载 Carpet Mod 1.4.128 或更新版本，并将其放入你的 mods/ 文件夹。
4. 安装 PlayerCarpetEx — 下载 PlayerCarpetEx-1.3.0.jar 文件并将其放入服务器 mods/ 文件夹。
5. 重启服务器 — 重启你的 Minecraft 服务器以加载所有模组。

验证安装

服务器启动后，你应该会看到以下日志消息：

[PlayerCarpetEx] Player Carpet Extension 已初始化！
[PlayerCarpetEx] Player Carpet Extension：游戏已启动。
[PlayerCarpetEx] Player Carpet Extension：服务器已加载。

你还可以运行 /version 或检查 Carpet Mod 规则列表 — PlayerCarpetEx 将作为已注册的 Carpet 扩展显示，版本号为 1.3.0。

---

🛠️ 命令

所有命令都需要权限等级 2（管理员身份）。基础命令是 /playerex。

注意： 在以下所有命令中，将 <player> 替换为实际的玩家名称。

物品栏管理

/playerex <player> inventory（或 /playerex <player> inventory view）

打开一个视觉 GUI 查看器，显示目标玩家的完整物品栏（副手、护甲、快捷栏和主物品栏）。GUI 使用 9×6 容器，并带有玻璃板分隔符以实现清晰布局。

/playerex Steve inventory

/playerex <player> inventory list

直接在聊天中打印目标玩家物品栏内容的详细文本列表。显示每个格子索引、物品名称和数量，并按快捷栏和主物品栏部分组织。

/playerex Steve inventory list

示例输出：

[CarpetEx] Steve 的物品栏
[CarpetEx]  --- 快捷栏（格子 0-8） ---
[CarpetEx]    [0] 钻石剑 x1
[CarpetEx]    [1] 空
[CarpetEx]    [2] 金苹果 x16
[CarpetEx]  --- 主物品栏（格子 9-35） ---
[CarpetEx]    [9] 橡木木板 x64
[CarpetEx]    [10] 圆石 x32

/playerex <player> inventory info <slot>

显示特定物品栏格子的详细信息，包括物品名称、当前数量和最大堆叠大小。

/playerex Steve inventory info 5

/playerex <player> inventory give <slot> <item> [count]

将指定的物品放入目标玩家物品栏的给定格子号中。如果未指定数量，默认为 1。数量范围从 1 到 64。

/playerex Steve inventory give 0 minecraft:diamond_sword 1
/playerex Steve inventory give 9 minecraft:golden_apple 64

/playerex <player> inventory remove <slot> [count]

从指定格子移除目标玩家物品栏中的物品。如果数量等于或超过当前堆叠大小，则完全清空该格子。默认移除 1 个物品。

/playerex Steve inventory remove 9 32
/playerex Steve inventory remove 0

/playerex <player> inventory clear

完全清空目标玩家的整个物品栏（快捷栏、主物品栏、护甲和副手）。请谨慎使用。

/playerex Steve inventory clear

/playerex <player> inventory swap <slot1> <slot2>

交换目标玩家物品栏中两个格子的内容。两个格子号必须介于 0 和 40 之间（格子 40 = 副手）。

/playerex Steve inventory swap 0 9
/playerex Steve inventory swap 36 37

/playerex <player> inventory set <slot> <item> [count]

将指定格子的内容设置为指定的物品和数量，替换之前的内容。类似于 give，但会覆盖现有堆叠。

/playerex Steve inventory set 0 minecraft:netherite_sword 1

/playerex <player> inventory count <item>

计算目标玩家物品栏中所有格子中特定物品的总数。用于快速检查资源数量。

/playerex Steve inventory count minecraft:diamond

示例输出：

[CarpetEx] 47个钻石

/playerex <player> inventory compact

通过将部分堆叠合并为完整堆叠，来整合目标玩家物品栏中所有可堆叠的物品。通过合并相同类型的物品来释放物品栏空间。

/playerex Steve inventory compact

/playerex <player> inventory drop <slot>

将指定格子中的物品丢弃在目标玩家附近的地面上。物品会从物品栏中物理弹出到世界中。

/playerex Steve inventory drop 36

---

自动切换系统

/playerex <player> use switch

切换目标玩家的自动切换快捷栏系统开启或关闭。首次启用时，系统将开始自动监控和补充玩家选中的快捷栏格子。

/playerex Steve use switch

/playerex <player> use switch true

明确启用目标玩家的自动切换功能。

/playerex Steve use switch true

/playerex <player> use switch false

明确禁用目标玩家的自动切换功能。如果物品栏锁处于活动状态，此操作也会释放它。

/playerex Steve use switch false

---

格子参考指南

格子范围	描述
0–8	快捷栏（从左到右）
9–35	主物品栏
36	靴子
37	护腿
38	胸甲
39	头盔
40	副手

---

🔧 技术细节

架构

该模组采用清晰、模块化的架构构建，由四个主要组件组成：

1. 命令模块 (commands/)

• PlayerInventoryCommand.java — 处理所有物品栏管理命令和 GUI 查看器系统。包含格子映射逻辑、玻璃板初始化和双向同步引擎。
• PlayerUseSwitchCommand.java — 处理自动切换切换命令和状态管理。

2. 处理器模块 (handler/)

• SwitchHandler.java — 自动切换核心引擎。在每个服务器刻运行，检查选中的快捷栏格子并执行物品轮换、物品栏拉取和锁定管理。

3. Mixin 模块 (mixin/)

• PlayerInventoryMixin.java — 钩入 PlayerInventory.setStack()、PlayerInventory.addStack() 和 PlayerInventory.markDirty() 以拦截物品栏修改，并在自动切换激活且物品栏耗尽时强制执行锁定。
• ServerPlayerEntityMixin.java — 钩入 ServerPlayerEntity.closeHandledScreen() 以检测玩家关闭物品栏查看器 GUI 的时刻，触发从查看器到目标的最终同步。

4. 核心模块

• PlayerCarpetExtension.java — 实现 ModInitializer 和 CarpetExtension 的主模组入口点。初始化所有系统并注册 Carpet 设置管理器。

同步系统

双向同步系统是该模组最关键的部分之一。它确保查看管理员和目标玩家始终看到一致的物品栏状态。

查看器 → 目标同步：

• 当查看器在 GUI 中修改任何物品时触发（通过 SimpleInventory.markDirty() 重写）。
• 遍历所有 54 个查看格子，检查 VIEW_TO_TARGET 映射数组，并将非玻璃物品复制到相应的目标物品栏格子。
• syncing 标志防止可能导致无限循环的重入调用。

目标 → 查看器同步：

• 每 10 个服务器刻（0.5 秒）通过 ServerTickEvents.END_SERVER_TICK 触发。
• 遍历所有 41 个目标物品栏格子，检查 TARGET_TO_VIEW 反向映射数组，并将物品复制到相应的查看格子。
• 仅在查看器不在初始化阶段时运行。

初始化保护：

• 当 GUI 首次打开时，syncing 和 initializing 标志都设置为 true。
• 这可以防止在初始填充查看物品栏期间产生任何副作用。
• 在所有物品和玻璃板放置完毕后，initializing 标志被清除。
• 在初始化块完成后，syncing 标志被清除。

格子映射

格子映射系统使用两个查找数组在 54 格查看容器和 41 格 Minecraft 玩家物品栏之间进行转换：

• VIEW_TO_TARGET[54] — 将每个查看容器格子（0–53）映射到相应的目标物品栏格子（-1 表示玻璃/未使用）。
• TARGET_TO_VIEW[41] — 从目标物品栏格子到查看容器格子的反向映射（-1 表示未映射）。

这种双向映射使得在两个方向上的高效同步成为可能。

---

🖼️ 画廊

图片	描述
	模组横幅艺术作品
	GUI 布局示意图，展示组织有序的物品栏视图
	功能概览插图
	自动切换快捷栏机制示意图
	游戏内物品栏查看器截图

---

🤝 兼容性

模组	兼容	备注
Carpet Mod 1.4.128+	✅ 是	必需依赖
Fabric API	✅ 是	必需依赖
Lithium	✅ 是	完全兼容
Sodium	✅ 是	仅客户端，无冲突
Indium	✅ 是	仅客户端，无冲突
ModMenu	✅ 是	将出现在模组列表中

---

📋 更新日志

v1.3.0 — 物品栏 GUI 大修

• 完全重写了物品栏查看系统，采用可视化 GUI 容器
• 添加了基于 54 格（9×6）GenericContainerScreenHandler 的查看器
• 实现了查看器与目标之间的双向同步（每 10 刻）
• 添加了玻璃板分隔符：蓝色染色玻璃用于护甲行，灰色染色玻璃用于快捷栏/物品栏分隔线
• 添加了 syncing 和 initializing 标志以防止初始化期间的重入同步
• 添加了正确的 VIEW_TO_TARGET 和 TARGET_TO_VIEW 格子映射数组
• 新的物品格子命令：give、remove、clear、swap、set、count、compact、drop
• 为 ServerPlayerEntity.closeHandledScreen() 添加了 Mixin 以检测 GUI 关闭事件
• 为 PlayerInventory 添加了 Mixin 以支持自动切换物品栏锁定

v1.2.0 — 自动切换系统

• 添加了自动切换快捷栏补充系统，包括快捷栏轮换、物品栏拉取和物品栏锁定
• 为 setStack、addStack 和 markDirty 拦截添加了 PlayerInventoryMixin
• 添加了 SwitchHandler，使用 ConcurrentHashMap 进行按玩家状态管理

v1.1.0 — 初始物品栏命令

• 添加了 /playerex <player> inventory list 和 /playerex <player> inventory info <slot>
• 修复了打开物品栏视图时物品消失的错误
• 使用 Brigadier 参数类型改进了命令结构

v1.0.0 — 首次发布

• 基本的 /playerex 命令结构
• 初始物品栏查看命令（基于文本）
• Carpet Mod 扩展注册

---

📄 许可证

该模组根据 MIT 许可证 发布。你可以自由地在任何项目中使用、修改和分发此模组，前提是包含原始许可证声明。

MIT 许可证

版权所有 (c) 2026 PlayerCarpetEx

特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人无限制地处理本软件的许可，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件副本的权利，并允许获得本软件的人这样做，但须满足以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。

---

🔗 链接

• Modrinth： PlayerCarpetEx
• 源代码： GitHub 仓库
• 问题反馈： 问题追踪器
• Carpet Mod： gnembon/fabric-carpet

---

为 Minecraft 服务器管理社区献上 ❤️