Dex Cosmetics
一款适用于 Fabric 1.21.1 的服务端外观模组。包含帽子、背部物品(披风、翅膀、背包)、物品皮肤以及视觉效果(粒子、发光轮廓、Bedrock 格式粒子)。100% 服务端安装 —— 原版客户端通过 Polymer 的自动托管资源包查看所有内容。
要求
- Minecraft: 1.21.1
- Mod loader: Fabric 0.19.2 或更高版本
- 仅服务端 — 客户端运行原版;无需在客户端安装
依赖
| 依赖项 |
版本 |
类型 |
作用 |
fabric-api |
0.116.12+1.21.1 |
必需 |
Core Fabric APIs(事件、命令、网络) |
fabric-language-kotlin |
1.13.11 / Kotlin 2.3.21 |
必需 |
该模组使用 Kotlin 编写 |
polymer |
0.9.19+1.21.1 |
必需 |
服务端自定义物品及模型注册 |
text-placeholder-api |
2.4.2+1.21 |
必需(传递性依赖) |
MiniMessage 风格文本解析 |
LuckPerms |
5.4 API |
可选 |
用于管理命令的权限检查;若未安装则回退至原版 OP 等级 |
Cobblemon |
1.7.3+1.21.1 |
可选 |
仅需要用于暴风雪粒子效果;在运行时进行门控控制 |
安装
- 将模组 jar 文件及其所有必需的依赖项(Fabric API、Fabric Language Kotlin、所有四个 Polymer 模块、sgui、placeholder-api)放入服务器的
mods/ 文件夹中。
- 启动服务器一次 —— 首次运行时,它会在
config/dex_cosmetics/ 生成默认设置文件、捆绑的示例外观数据,以及用于添加自定义内容的目录结构。
- (可选)安装 LuckPerms 以便通过权限访问管理命令。若无 LuckPerms,管理命令需 OP 等级 4。
- (可选)安装 Cobblemon 以启用暴风雪粒子效果。若不安装,这些外观仍可加载但不会渲染任何内容。
客户端正常连接即可 —— Polymer 会自动托管资源包并在玩家加入时提供。该资源包默认标记为“必需”;拒绝接受的玩家将被踢出。此行为可配置。
配置
全局配置 — config/dex_cosmetics/config.json
{
"require_resource_pack": true,
"resource_pack_kick_message": "This server requires the Dex Cosmetics resource pack.",
"autosave_interval_seconds": 300,
"particle_tick_budget_per_player": 32,
"admin_permission": "dexcosmetics.admin",
"allow_item_skin_sharing": true,
"rename_item_to_skin_name": false,
"resource_pack_mode": "auto",
"custom_model_data_start": 2000,
"menu_categories": {
"ITEM": true,
"HAT": true,
"BACK": true,
"EFFECT": true,
"BALLOON": false,
"POKEMON": false
},
"menu_focus": "HAT"
}
require_resource_pack — 当为 true 时,拒绝资源包的客户端会被踢出,并显示 resource_pack_kick_message 中的消息。设置为 false 允许无资源包的玩家进入(他们将看到原版所有内容)。
autosave_interval_seconds — 目前仅为信息提示;玩家数据在每次授予/撤销/装备时持久化保存。
particle_tick_budget_per_player — 目前仅为信息提示;粒子外观通过每个外观的 interval_ticks 进行节流控制。
admin_permission — 检查 LuckPerms 权限节点以执行 /cosmetics give/take/list/reload/generatepack。若无 LuckPerms,则需要 OP 等级 4。
allow_item_skin_sharing — 当为 true(默认值)时,带有皮肤的物品在掉落或交易时保留其皮肤。当为 false 时,非所有者捡起物品的瞬间会剥离皮肤组件。
rename_item_to_skin_name — 当为 true 时,应用了皮肤的物品会显示外观的显示名称而非原版物品名称。名称覆盖发生在客户端同步时,因此交易不会永久重命名底层物品堆栈。
外观定义 — config/dex_cosmetics/cosmetics/<type>/<id>.json
每个外观一个 JSON 文件,分为四个子目录:
hats/ — 头部装备(type: HAT)
back/ — 披风、翅膀、背包(type: BACK)
items/ — 手持物品皮肤(type: ITEM)
effects/ — 粒子、发光、暴风雪(type: EFFECT)
每个文件定义如下:
{
"id": "my_cosmetic",
"type": "HAT",
"display_name": "<gold>My Hat</gold>",
"description": ["Lore line 1", "Lore line 2"],
"model": "dex_cosmetics:hats/my_cosmetic",
"texture": "dex_cosmetics:hats/my_cosmetic/my_cosmetic",
"model_parent": "minecraft:item/generated",
"transform": {
"offset_x": 0, "offset_y": 0, "offset_z": 0,
"scale_x": 1, "scale_y": 1, "scale_z": 1
}
}
按类型说明:
- HAT — 使用
transform 将偏移量和缩放比例烘焙到模型的 display.head 视角中。
- BACK — 仅读取
scale.x(通过 SCALE 属性实现均匀缩放)。位置由原版盔甲架挂载逻辑固定。
- ITEM — 需要
item_skin: { compatible_items: [...] }。每一项是一个物品 ID(如 minecraft:diamond_sword)或标签(如 #minecraft:swords)。
- EFFECT — 需要
effect: { kind: "particle" | "glow" | "snowstorm", ... }。请参阅 cosmetics/effects/ 中的捆绑示例。
模型 — config/dex_cosmetics/model/<type>/<id>.json
在此处放置以外观 ID 命名的 Blockbench 导出文件;资源包将自动使用它。如果缺失,将根据外观的 model_parent 和 texture 字段创建一个简单的 {parent, layer0} 模型。
对于手持工具(物品皮肤等),请确保模型具有 "parent": "minecraft:item/handheld" 以及正确的 display 设置。
纹理 — config/dex_cosmetics/textures/<type>/<id>/<png>
位于 textures/hats/my_hat/example.png 的文件在资源包中将表现为 assets/dex_cosmetics/textures/hats/my_hat/example.png,并可作为 dex_cosmetics:hats/my_hat/example 引用。与 PNG 文件并列的 .mcmeta 文件会被原样传递,从而支持动画纹理。
暴风雪粒子 — config/dex_cosmetics/snowstorm_particles/<id>.particle.json
Bedrock 格式的粒子定义。JSON 内部的 description.identifier 字段是 EFFECT 外观通过 effect.snowstorm.particle_id 引用的内容。Cobblemon 的 BedrockParticleEffectRepository 会在打包构建时拾取它们。
功能
外观类型
帽子 — 通过伪造的 EntityEquipmentUpdateS2CPacket 发送,以便原版头盔骨骼渲染管线进行渲染。支持头部旋转、基于俯仰角的前向偏移以及完美追踪。佩戴者原本的头盔仍保留在背包中不受影响。
背部物品 — 将不可见的标记实体作为乘客挂载在佩戴者身上,并将外观物品放置在头部装备槽中。在 SWIMMING(游泳)/ FALL_FLYING(滑翔翼飞行)/ SLEEPING(睡觉)/ SPIN_ATTACK(旋转攻击)姿态下自动隐藏,并在退出姿态时重新生成。
物品皮肤 — 玩家通过在外观 GUI 中按住目标物品并点击皮肤图标来应用皮肤。可选配置:当非所有者拾取该物品时移除皮肤。
特效 — 通过 kind 字段提供三种风格:
- 粒子:原版粒子。两种创建模式 — 内置精选形状(
point / trail / halo / orbit / square),由粒子类型 + 数量 + 半径参数化;或者在佩戴者位置以 op 级别 + 静默反馈运行原始原版命令。
- 发光:每 tick 刷新的原版 GLOWING(发光)状态效果。通过记分板队伍成员资格为每个外观设置轮廓颜色(每种 Formatting 颜色对应一个
dex_glow_<formatting> 队伍)。
- 暴风雪:通过 Cobblemon 的
SpawnSnowstormParticlePacket 实现 Bedrock 格式的粒子爆发。由 interval_ticks 限制频率,在佩戴者周围 broadcast_radius 方块范围内广播。
按玩家所有权
基于 SQLite 的外观按玩家所有权管理。玩家可以在 GUI 中看到其完整目录,但只能装备他们拥有的外观。管理员通过命令授予或撤销权限。
存储位于 <world>/dex_cosmetics/cosmetics.db。包含两个表:player_owned (uuid, cosmetic_id) 和 player_equipped (uuid, type, cosmetic_id)。架构会在首次运行时创建。
箱子 / 商店集成
现有的箱子插件、商店和战利品表可通过执行以下命令发放外观:
/cosmetics give <player> <cosmetic_id>
(或使用 /cosmetics take 来撤销)。这是支持的集成点——任何能够执行控制台命令的东西都可以给予饰品。
玩家命令
| 命令 |
权限 |
描述 |
/cosmetics |
无 |
打开饰品 GUI |
/cosmetics remove |
无 |
移除手持物品上应用的任何皮肤 |
/cosmetics give <player> <id> |
管理员 |
授予饰品所有权 |
/cosmetics take <player> <id> |
管理员 |
撤销所有权 |
/cosmetics list <player> |
管理员 |
列出玩家拥有的饰品 |
/cosmetics reload |
管理员 |
重新加载所有饰品配置并重建资源包 |
/cosmetics generatepack |
管理员 |
手动生成资源包 |
资源包组装发生在 SERVER_STARTING 阶段,在标签加载之后:
CosmeticItems.registerAll 通过 PolymerResourcePackUtils.requestModel 为每个饰品以及每种(皮肤,物品)变体分配一个 CMD。
DexCosmetics.buildResourcePack 触发 Polymer 的 RESOURCE_PACK_CREATION_EVENT。
- 事件处理器运行
pipeUserTextures、pipeSnowstormParticles、PackModelGenerator.writeAll、GlowIconGenerator.writeAll,并写入方块和粒子图集覆盖。
- polymer-autohost 在后续加入时提供生成的
polymer/resource_pack.zip。
制作一个饰品
- 模型:在 Blockbench 中设计外观。使用 Java 方块/物品项目类型,以便导出时包含
parent 和 display 区块。
- 纹理:导出 PNG 文件,并将其放置于
config/dex_cosmetics/textures/<type>/<id>/<id>.png 下。
- 外观配置:在
config/dex_cosmetics/cosmetics/<type>/<id>.json 下编写 JSON 文件(参考内置示例的结构)。
- 模型文件(可选但常见):如果你有一个包含多种纹理、自定义元素等的 Blockbench 导出文件,请将其保存为
config/dex_cosmetics/model/<type>/<id>.json。
- 重载:执行
/cosmetics reload 或重启服务器。玩家需要重新连接以下载更新后的资源包。
Dex Cosmetics
A server-side cosmetics mod for Fabric 1.21.1. Hats, back items (capes, wings, backpacks), item skins, and visual effects (particles, glow outlines, Bedrock-format particles). 100% server-installed — vanilla clients see everything through Polymer's auto-served resource pack.
Requirements
- Minecraft: 1.21.1
- Mod loader: Fabric 0.19.2 or newer
- Server-side only — clients run vanilla; no client install required
Dependencies
| Dependency |
Version |
Type |
Role |
fabric-api |
0.116.12+1.21.1 |
Required |
Core Fabric APIs (events, commands, networking) |
fabric-language-kotlin |
1.13.11 / Kotlin 2.3.21 |
Required |
Mod is written in Kotlin |
polymer |
0.9.19+1.21.1 |
Required |
Server-side custom items + model registration |
text-placeholder-api |
2.4.2+1.21 |
Required (transitive) |
MiniMessage-style text parsing |
LuckPerms |
5.4 API |
Optional |
Permission checks for admin commands; falls back to vanilla op-level if absent |
Cobblemon |
1.7.3+1.21.1 |
Optional |
Needed only for snowstorm-particle effects; gated at runtime |
Installation
- Drop the mod jar into your server's
mods/ folder along with its required dependencies (Fabric API, Fabric Language Kotlin, all four Polymer modules, sgui, placeholder-api).
- Start the server once — on first run it generates
config/dex_cosmetics/ with the default settings file, bundled example cosmetics, and the directory layout for adding your own.
- (Optional) Install LuckPerms if you want permission-based admin command access. Without it, admin commands gate on op level 4.
- (Optional) Install Cobblemon if you want snowstorm-particle effects. Without it those cosmetics still load but render nothing.
Clients connect normally — Polymer-autohost serves the resource pack automatically on join. The pack is marked required by default; players who decline will be kicked. This is configurable.
Configuration
Global config — config/dex_cosmetics/config.json
{
"require_resource_pack": true,
"resource_pack_kick_message": "This server requires the Dex Cosmetics resource pack.",
"autosave_interval_seconds": 300,
"particle_tick_budget_per_player": 32,
"admin_permission": "dexcosmetics.admin",
"allow_item_skin_sharing": true,
"rename_item_to_skin_name": false,
"resource_pack_mode": "auto",
"custom_model_data_start": 2000,
"menu_categories": {
"ITEM": true,
"HAT": true,
"BACK": true,
"EFFECT": true,
"BALLOON": false,
"POKEMON": false
},
"menu_focus": "HAT"
}
require_resource_pack — when true, clients who decline the pack are kicked with resource_pack_kick_message. Set false to allow players in without it (they'll see vanilla everything).
autosave_interval_seconds — currently informational; player data is persisted on every grant/revoke/equip.
particle_tick_budget_per_player — currently informational; particle cosmetics throttle via interval_ticks per cosmetic.
admin_permission — LuckPerms permission node checked for /cosmetics give/take/list/reload/generatepack. Without LuckPerms, op-level 4 is required.
allow_item_skin_sharing — when true (default), skinned items keep their skin when dropped/traded. When false, the skin component is stripped the moment a non-owner picks the item up.
rename_item_to_skin_name — when true, items with an applied skin show the cosmetic's display name instead of the vanilla item name. Name override happens at sync time on the client copy, so trading doesn't permanently rename the underlying stack.
Cosmetic definitions — config/dex_cosmetics/cosmetics/<type>/<id>.json
One JSON file per cosmetic, grouped into four subdirectories:
hats/ — head equipment (type: HAT)
back/ — capes, wings, backpacks (type: BACK)
items/ — held-item skins (type: ITEM)
effects/ — particles, glow, snowstorm (type: EFFECT)
Each file defines:
{
"id": "my_cosmetic",
"type": "HAT",
"display_name": "<gold>My Hat</gold>",
"description": ["Lore line 1", "Lore line 2"],
"model": "dex_cosmetics:hats/my_cosmetic",
"texture": "dex_cosmetics:hats/my_cosmetic/my_cosmetic",
"model_parent": "minecraft:item/generated",
"transform": {
"offset_x": 0, "offset_y": 0, "offset_z": 0,
"scale_x": 1, "scale_y": 1, "scale_z": 1
}
}
Per type:
- HAT — uses
transform to bake an offset/scale into the model's display.head perspective.
- BACK — only
scale.x is read (uniform scale via SCALE attribute). Position is fixed by vanilla armor-stand mount logic.
- ITEM — needs
item_skin: { compatible_items: [...] }. Each entry is an item id (minecraft:diamond_sword) or tag (#minecraft:swords).
- EFFECT — needs
effect: { kind: "particle" | "glow" | "snowstorm", ... }. See bundled examples in cosmetics/effects/.
Models — config/dex_cosmetics/model/<type>/<id>.json
Drop a Blockbench export here named after the cosmetic id; the pack will use it automatically. If absent, a simple {parent, layer0} model is created from the cosmetic's model_parent and texture fields.
For held tools (item skins, etc.), make sure the model has "parent": "minecraft:item/handheld" and a proper display.
Textures — config/dex_cosmetics/textures/<type>/<id>/<png>
A file at textures/hats/my_hat/example.png appears in the pack as assets/dex_cosmetics/textures/hats/my_hat/example.png and is referenceable as dex_cosmetics:hats/my_hat/example. .mcmeta files alongside PNGs pass through, so animated textures work.
Snowstorm particles — config/dex_cosmetics/snowstorm_particles/<id>.particle.json
Bedrock-format particle definitions. The description.identifier field inside the JSON is what an EFFECT cosmetic references via effect.snowstorm.particle_id. Cobblemon's BedrockParticleEffectRepository picks them up at pack-build time.
Features
Cosmetic types
Hats — sent via fake EntityEquipmentUpdateS2CPacket so vanilla's helmet-bone armor pipeline renders them. Head rotation, pitch-based forward shift, perfect tracking. The wearer's real helmet stays in their inventory untouched.
Back items — invisible marker entity mounted as a passenger of the wearer, with the cosmetic item in the HEAD equipment slot. Automatically hides during SWIMMING / FALL_FLYING / SLEEPING / SPIN_ATTACK poses and respawns on pose exit.
Item skins — players apply skins through the cosmetics GUI by holding the target item and clicking the skin icon. Optional config to strip the skin when a non-owner picks the item up.
Effects — three flavors via the kind field:
- Particle: vanilla particles. Two authoring modes — built-in curated shapes (
point / trail / halo / orbit / square) parameterized by particle type + count + radius, OR raw vanilla commands run at the wearer's position with op-level + silent feedback.
- Glow: vanilla GLOWING status effect refreshed each tick. Per-cosmetic outline color via scoreboard team membership (one
dex_glow_<formatting> team per Formatting color).
- Snowstorm: Bedrock-format particle burst via Cobblemon's
SpawnSnowstormParticlePacket. Throttled by interval_ticks, broadcast within broadcast_radius blocks of the wearer.
Per-player ownership
SQLite-backed per-player ownership of cosmetics. Players see their full catalog in the GUI but can only equip cosmetics they own. Admins grant/revoke via commands.
Storage lives in <world>/dex_cosmetics/cosmetics.db. Two tables: player_owned (uuid, cosmetic_id) and player_equipped (uuid, type, cosmetic_id). Schema is created on first run.
Crate / shop integration
Existing crate plugins, shops, and loot tables grant cosmetics by running:
/cosmetics give <player> <cosmetic_id>
(or /cosmetics take to revoke). This is the supported integration point — anything that can execute a console command can give cosmetics.
Player commands
| Command |
Permission |
Description |
/cosmetics |
none |
Opens the cosmetics GUI |
/cosmetics remove |
none |
Removes any applied skin from the held item |
/cosmetics give <player> <id> |
admin |
Grants ownership of a cosmetic |
/cosmetics take <player> <id> |
admin |
Revokes ownership |
/cosmetics list <player> |
admin |
Lists what the player owns |
/cosmetics reload |
admin |
Reloads all cosmetic configs and rebuilds the resource pack |
/cosmetics generatepack |
admin |
Manually generates resource pack |
Resource pack assembly happens at SERVER_STARTING after tag load:
CosmeticItems.registerAll allocates a CMD per cosmetic + per (skin, item) variant via PolymerResourcePackUtils.requestModel.
DexCosmetics.buildResourcePack triggers Polymer's RESOURCE_PACK_CREATION_EVENT.
- The event handlers run
pipeUserTextures, pipeSnowstormParticles, PackModelGenerator.writeAll, GlowIconGenerator.writeAll, and write the blocks + particles atlas overrides.
- polymer-autohost serves the resulting
polymer/resource_pack.zip on subsequent joins.
Making a cosmetic
- Model: in Blockbench, design the cosmetic. Use Java Block/Item project type so the export includes
parent and display blocks.
- Texture: export the PNG and drop it under
config/dex_cosmetics/textures/<type>/<id>/<id>.png.
- Cosmetic config: write a JSON file under
config/dex_cosmetics/cosmetics/<type>/<id>.json (mirror the bundled examples).
- Model file (optional but common): if you have a Blockbench export with multiple textures, custom elements, etc., save it as
config/dex_cosmetics/model/<type>/<id>.json.
- Reload:
/cosmetics reload or restart the server. Players need to reconnect to re-download the updated pack.
评论 0
登录后参与评分
还没有评论,来抢沙发吧