Cosmetics

3D 装扮、物品模型装扮和皮肤，配有衣柜菜单和每位玩家独立的存储。

私有v0.0.2菜单与视觉

依赖TypeWriter0.9GUIEntityCraftEngine可选Profiles可选

专为 BornToCraft 服务器网络打造。此扩展仅作参考文档，不对外分发。

支持

概述

Cosmetics 让玩家为自己装扮并自定义装备。它涵盖两种装饰品。**实体装饰品（Entity cosmetics）**是跟随玩家的 3D 模型（帽子、背包、翅膀、光环），还可附带粒子效果。**物品装饰品（Item cosmetics）会改变玩家所携带的真实物品（例如一件盔甲或一把剑）的模型，因此新外观在手持、穿戴或丢弃该物品时也会显示。另一个独立的皮肤（skins）**功能则会给玩家手中的物品套上一层外观。

玩家在衣柜菜单中挑选装饰品，每个分类对应一个标签页。当装饰品没有权限要求、玩家持有它的权限，或者管理员或其他条目已为其解锁时，它就是可用的。已装备和已解锁的装饰品会按玩家保存在 artifact 中。

该扩展运行于 TypeWriter 的 BTC 构建版（BTC Core，Paper/Folia），此处的文档仅供参考。0.0.2 版本是早期发布版。

功能

• 实体装饰品 — 将任意实体定义（物品展示实体、BetterModel 模型…）附着到玩家身上，可相对于身体或头部，或固定位置。
• 物品装饰品 — 替换匹配物品的 item_model 和穿戴外观，并在装饰品被移除时还原。
• 粒子 — 为装饰品附加粒子效果。
• 分类和标签页 — 将装饰品按分类分组，每个分类一个标签页，并带有拥有状态过滤器（全部、已拥有、未拥有）。
• 每类一件 — 玩家在每个分类中同一时间只能穿戴一件装饰品。
• 解锁 — 免费、通过权限、通过命令，或来自其他条目。
• 皮肤 — 为手持物品套用的外观，在专用菜单中选择，物品被丢弃时移除。
• 实体上的装饰品 — 通过实体数据把装饰品附着到 NPC 或其他实体上。
• 占位符和 fact — 在其他插件中显示数量，并在条件（criteria）中测试拥有状态。

安装

1. 安装 GUI 扩展（BTC 构建版中为 GuiAndDialogs），两个菜单都会用到它。
2. 对于实体装饰品，请安装 TypeWriter 的 Entity 扩展，或提供实体定义的其他扩展。物品装饰品和皮肤不需要它。
3. 可选：如果你的物品装饰品针对的是 CraftEngine 物品，请安装 CraftEngine；如果装饰品必须跟随活动档案，请安装 Profiles 扩展。
4. 将 Cosmetics 的 JAR 放入 plugins/Typewriter/extensions/，然后重启服务器。
5. 在你的资源包中提供这些模型：物品装饰品和皮肤使用的 item_model 键（Minecraft 1.21.4 或更高版本），以及用于穿戴盔甲外观的 assets/<namespace>/textures/entity/equipment/ 纹理。

快速上手

创建一顶玩家通过权限解锁的帽子：

1. 在 TypeWriter 网页面板中，打开一个 manifest 页面，添加一个 Cosmetic Category 条目。将其命名为 Hats，并选择一个 icon。
2. 添加一个 Cosmetic Definition 条目。将 category 设为分类条目的 ID（如果没有 ID，则为其名称），并设置 priority、menuIcon 和 permission（例如 cosmetics.hat.top_hat）。
3. 在 model 中引用一个实体定义，例如装有你的帽子模型的物品展示实体。将 rotationMode 设为 RELATIVE_TO_HEAD，并调整 offset 和 rotationOffset。
4. 添加一个 Player Cosmetics artifact，以便保存已装备和已解锁的装饰品。让 artifactId 留给网页面板自动生成。
5. 添加一个 BTC Cosmetics Menu 动作。在 layoutPool 中构建它的布局，放入“菜单”部分所描述的五个 cosmetics_button: 标记；如果你使用共享的菜单底板，请设置 baseMenuId。
6. 发布。把权限授予一位测试玩家，或运行 /tw cosmetics give <player> <cosmetic entry id>，然后运行 /tw cosmetics 并装备这顶帽子。

使用条目 ID

解锁列表、已装备列表、give 命令和 Has Cosmetic fact 都是通过条目 ID，而不是 cosmeticId 字段来标识装饰品的。cosmeticId 字段只会在菜单中以 {cosmetic_id} 标记的形式显示。

工作原理

当定义带有 itemModel 或 equipmentAssetId，并且同时列出了 applicableCraftEngineIds 或 applicableItems 时，它就是一个物品装饰品。所有其他定义都是实体装饰品，并使用 model。物品装饰品会在每次刷新的每个 tick 应用到玩家物品栏中匹配的物品上，并且原始模型会保留在物品上，以便还原。

菜单

BTC Cosmetics Menu 是一个 GUI 条目，每个分类对应一个视图，由你的 Cosmetic Category 条目生成。被某个装饰品使用但从未声明的分类，仍然会显示为一个标签页。请在你的布局中，使用标签 cosmetics_button:<TYPE> 放入这些标记：

标记	位置	作用
CATEGORY_TAB	可重复	每个分类一个标签页。标记变量：{category_id}、{category_name}、{owned}、{total}。
COSMETIC_SLOT	可重复	当前标签页的每个装饰品一个槽位，按 priority 排序。点击会装备，如果已穿戴则取消装备。未拥有的装饰品会显示但无法点击。标记变量：{cosmetic_id}、{cosmetic_name}、{category_name}、{state}。
SORT_TOGGLE	一次	在全部、已拥有和未拥有之间循环切换。标记变量：{current_filter}。玩家离开时过滤器会被重置。
CLEAR_CATEGORY	一次	取消装备当前标签页的装饰品。
PAGE_NAV	一次	左键点击为下一页，右键点击为上一页。标记变量：{page}、{total_pages}、{page_indicator}。当一页就够用时会隐藏。

categoryView 是为每个分类克隆的模板（其名称支持 {category_name} 和 {category_id}），categoryViewIdPrefix（默认为 cosmetic_）是视图 id 的前缀。没有关闭或页码指示的标记：关闭由底板处理，计数器则由 PAGE_NAV 携带。这些按钮的默认文本是法语的。

皮肤菜单是独立的：它通过 Open Skins Menu 动作或 /tw skins 打开，显示适用于玩家主手物品的皮肤，并由 Skins Menu Config 条目进行布局（skinSlots、已解锁、激活和锁定皮肤的模板，以及按钮）。左键点击已解锁的皮肤即可应用，按钮则可以移除皮肤，或将其应用于物品栏中所有兼容的物品。被丢弃的带皮肤物品会失去其皮肤。

配置

装饰品和皮肤通过两个 artifact 存储，在启动约一秒后加载，并在每次更改后的几秒保存：

• Player Cosmetics 按玩家存储已解锁的装饰品，以及每个分类中已装备的那一件。
• Player Skins 存储已解锁的皮肤以及每种物品类型所选的皮肤。

档案与已存储的数据

安装 Profiles 扩展后，已装备的装饰品会存储在玩家的活动档案下，而不是其 UUID 下。之前以 UUID 保存的装饰品不会被删除，但再也找不到它们了。在已经保存了真实玩家数据的服务器上，请在安装或更新（且存在 Profiles）之前先迁移这些键。解锁记录始终按玩家 UUID 存储。

命令

Cosmetics 命令是 TypeWriter 命令的子命令，因此以 /typewriter 或 /tw 开头。

命令	说明
/tw cosmetics 或 /tw cosmetics open	打开装饰品菜单。需要 cosmetics.use。
/tw cosmetics give <player> <cosmetic>	解锁一件装饰品，按其条目 ID 指定。需要 cosmetics.admin。
/tw cosmetics remove <player> <cosmetic>	移除一个解锁。需要 cosmetics.admin。
/tw cosmetics reset <player>	清除玩家的装饰品。需要 cosmetics.admin。
/tw skins 或 /tw skins open	为手中的物品打开皮肤菜单。需要 skins.use。
/tw skins give <player> <skin>	按 skinId 解锁一个皮肤。需要 skins.admin。
/tw skins remove <player> <skin>	移除一个皮肤解锁。需要 skins.admin。
/tw skins reset <player>	清除玩家的皮肤。需要 skins.admin。

菜单点击使用由扩展处理的内部命令 cosmetics ... 和 skins ...。它们并非用于手动输入。

权限

权限	授予
cosmetics.use	/tw cosmetics 和 /tw cosmetics open。
cosmetics.admin	装饰品的 give、remove 和 reset。
skins.use	/tw skins 和 /tw skins open。
skins.admin	皮肤的 give、remove 和 reset。
装饰品的 permission	你自行选择的、用于解锁某一件装饰品的权限。
皮肤的 permission	你自行选择的、用于解锁某一个皮肤的权限。

占位符

这些是 cosmetics expansion 的 MiniPlaceholders 标签。请将 cat 替换为分类 ID 或名称，将 id 替换为装饰品条目 ID。

占位符	返回值
<cosmetics_total_unlocked>	玩家已解锁的装饰品数量。
<cosmetics_total_available>	服务器上的装饰品定义数量。
<cosmetics_category_unlocked:cat>	该分类中已解锁的装饰品。
<cosmetics_category_total:cat>	该分类中的装饰品数量。
<cosmetics_is_unlocked:id>	true 或 false。
<cosmetics_is_active:id>	当该装饰品已装备时为 true。
<cosmetics_active:cat>	该分类中已装备的装饰品的 ID，没有时为空。

<cosmetics_category_unlocked:cat> 只统计通过命令或其他条目解锁的装饰品，不包括通过权限可用的装饰品。

条目

11 个条目，由扩展源码生成。

动作2

• BTC Cosmetics MenuBTC Cosmetics Menu
• Open Skins Menu ActionOpens the skins menu

事实2

• Has Cosmetic FactChecks if a player has a specific cosmetic unlocked.
• Has Skin FactVérifie si un joueur possède un skin spécifique.

实体数据1

• Cosmetic Entity DataAttach cosmetics to an entity definition

构件2

• Player Cosmetics ArtifactStores player unlocked cosmetics
• Player Skins ArtifactStores player selected skins

清单4

• Cosmetic CategoryDéfinition d'une catégorie de cosmétiques (ex: Chapeaux, Capes)
• Cosmetic DefinitionDefine a 3D Cosmetic
• Skin DefinitionDéfinition d'une catégorie de skins (wraps) pour les items
• Skins Menu ConfigConfiguration du menu des skins

故障排查

菜单提示 “Aucun menu de cosmétiques n'est configuré”。 没有发布任何 BTC Cosmetics Menu 条目。/tw cosmetics 会打开它找到的第一个。

某个分类标签页是空的，或缺少某件装饰品。 装饰品上的 category 必须与分类条目的 ID（没有 ID 时为名称）匹配，不区分大小写。与任何分类条目都不匹配的名称，仍然会创建一个自己的标签页。

模型始终没有出现。 实体装饰品需要 model 引用一个实体定义。带有 itemModel 但没有 applicableItems 或 applicableCraftEngineIds 的定义不是物品装饰品，会回退到实体路径。对于物品装饰品，itemModel 键必须是有效的命名空间键（namespace:path）；无效的键会被记录一次，内容为 “Invalid itemModel”。

物品模型在物品栏里变了，但在身上没变。 itemModel 只会改变物品在手中和物品栏中的外观。对于盔甲，还要将 equipmentAssetId 设为该材质的装备资源（例如 armors:enderite），不带部件名称。只有当被穿戴的物品已经带有 equippable 组件时才会应用。

CraftEngine 物品没有获得装饰品。 请使用带有 CraftEngine id 的 applicableCraftEngineIds（例如 armors:enderite_helmet）。CraftEngine 物品是通过 id 而不是材质来识别的，因此 applicableItems 不会匹配它。

已装备的装饰品或解锁记录丢失。 请将这些 artifact 添加到已发布的页面中。日志会报告缺少 artifact，或 “has no generated artifact id”，没有它们就不会保存任何内容。如果最近安装了 Profiles 扩展，请参阅上面的警告。

其他玩家看不到我的装饰品。 实体装饰品是虚拟实体。如果日志显示 “Viewer method ... unavailable ... owner-only fallback active”，说明所使用的 Entity 扩展不允许额外的观看者，只有所有者能看到该装饰品。

/tw skins 提示该物品没有皮肤。 手持物品必须与某个至少列出一个皮肤的 Skin Definition 的 applicableItems 中的某件物品匹配，并且必须发布了皮肤菜单条目。消息文本来自 Skins Menu Config 条目。

相关扩展

• GUI — 菜单布局和底板。
• Profiles — 装饰品可以跟随活动档案。
• BetterModel — 可用作实体装饰品的 3D 模型。