框架
此模组在 Fabric 和 NeoForge 上为 Minecraft 1.21.1 渲染玩家模型上的外观饰品。它可以独立运行(使用原版护甲栏位),同时也支持 Accessories 模组、Mega Showdown 模组 以及 Genesis Forms,安装这些模组后,所有栏位的物品均可进行渲染。以上三个模组均为可选;仅 GeckoLib(以及在 Fabric 上需要 Fabric API)是必需的。渲染通过自定义管线完成,该管线使用 Geckolib,从而支持动画附件以及纹理的透明度和自发光等特性。
该模组仅包含通用物品,其许多方面可以通过数据包 JSON 文件及配套的资源包进行克隆和覆盖。这允许用户添加自己的自定义外观饰品,使其佩戴在 Accessories 和 Mega Showdown 提供的任意栏位中,并为 Mega Showdown 和 Genesis Forms 的关键物品赋予独特的外观。
数据包
新物品本质上是带有 NBT 数据的现有通用物品的副本。要覆盖通用物品的外观,必须在数据包中指定它们,结构为 data/your_namespace/cosmetic/newitem.json。
外观饰品使用通用的外观物品,它会根据 JSON 中的 "slot" 字段放入相应的栏位:
/give @s piscosmetics:cosmetic[custom_data={cosmetic:"your_namespace:my_cool_hat"}]
? your_datapack/
├── pack.mcmeta
├── pack.png
└── ? data/
└── ? your_namespace/
└── ? cosmetic/
├── my_cool_hat.json
├── special_sword.json
└── ...
JSON 文件的内容决定了带 NBT 标签物品的各种属性。除 "slot" 外,所有字段都是可选的,如果留空将回退到默认值。可用字段如下:
{
"slot": "feet",
"name": "Dragon Boots",
"color": "gold",
"model": "your_namespace:cosmetic_feet",
"texture": "your_namespace:cosmetic_feet",
"animation": "your_namespace:cosmetic_feet",
"attach": "right_leg",
"translate_x": 0.1,
"translate_y": 0.2,
"translate_z": -0.1,
"rotate_x": 5.0,
"rotate_y": 10.0,
"rotate_z": 0.0,
"scale": 0.9,
"hide_armor": ["feet", "elytra"],
"icon": "your_namespace:item/cosmetic_feet",
"copyable": true,
"particle_emitters": [
{
"trigger": "walking",
"particle": "minecraft:end_rod",
"rate": 5,
"spread": 0.3,
"count": 2,
"offset_y": 0.1
},
{
"trigger": "sprinting",
"particle": "piscosmetics:cosmetic_particle",
"rate": 10,
"spread": 0.5,
"count": 1,
"offset_y": 0.5,
"custom_size": 0.5,
"lifetime": 20,
"texture": "your_namespace:lettera"
},
{
"trigger": "jumping",
"particle": "minecraft:entity_effect",
"rate": 3,
"spread": 1.0,
"count": 5,
"offset_y": 0.0,
"color": "#FF5500"
}
]
}
-
"slot":指定外观饰品所在的库存栏位;可以是 Accessories API 中的某个栏位、Mega Showdown 的某个栏位,或原版护甲栏位。可用栏位包括:
-
Accessories 栏位
"hat"
"back"
"belt"
"cape"
"charm"
"face"
"hand"
"necklace"
"ring"
"shoes"
"wrist"
"anklet"
-
Mega Showdown 栏位
"dynamax_slot"
"mega_slot"
"tera_slot"
"z_slot"
-
原版栏位
"head"
"chest"
"legs"
"feet"
使用 Accessories 和 Mega Showdown 栏位需要安装相应模组;原版栏位始终可用,并且可以像护甲一样通过右键点击装备。如果服务器上不存在某个栏位,则无法在该服务器上装备。若要使用其他模组或数据包添加的栏位,还需将该栏位对应的物品标签中添加 piscosmetics:cosmetic,即 data/accessories/tags/item/<slot>.json。
-
"name":物品在背包中显示的名称
-
"color":名称在所有显示位置的颜色,可以使用颜色名称如 "gold" 或十六进制代码如 "#FF8800"。名称默认为青色(aqua)。
-
"model"、"texture"、"animation":你的 .geo.json 模型文件、纹理文件和动画文件的命名空间与文件名。有关如何格式化并在资源包中放置这些文件的信息,请参阅本指南的资源包部分。
-
"attach":指定饰品附着并随其在所有常规 Minecraft 身体动画中移动的骨骼部位。请注意,成对渲染的栏位,即 "shoes"、"legs" 和 "feet" 无法以此方式覆盖。有效的玩家骨骼包括:
"head"
"body" 或 "chest"
"left_arm"
"right_arm"
"left_leg"
"right_leg"
-
偏移量:
"translate_x":向左(+)或向右(-)移动饰品。
"translate_y":向上(+)或向下(-)移动饰品。
"translate_z":向前(+)或向后(-)移动饰品。
"rotate_x":向前(+)或向后(-)倾斜饰品。
"rotate_y":向左(+)或向右(-)旋转饰品。
"rotate_z":向左(+)或向右(-)翻滚饰品。
"scale":在所有维度上缩放饰品的大小。请注意,这是一个覆盖值,不会像其他偏移值那样累加到任何隐藏默认值上。
-
"hide_armor":指定不渲染的原版护甲栏位,以防其与你的外观饰品发生穿插。可以是单个栏位或列表,如 ["chest", "legs"]。"elytra" 是一个特殊值,专门用于仅禁用鞘翅渲染;同样,"chest" 不会影响鞘翅的渲染。
-
"icon":使用资源包中的 .png 文件覆盖该物品在手部和掉落状态下的纹理。若省略此字段,手部和地面渲染器将直接使用外观模型本身。
-
"copyable":设置为 false 以禁止复制此外观的蓝图。详见“蓝图”部分。
-
"key_items" 和 "render_for":用于关键物品外观。详见“关键物品”部分。
-
"particle_emitters":这是一个较复杂的字段,允许你以列表形式添加任意数量的粒子发射器,并将其锚定到外观上。每个发射器均可完全自定义,并支持基于你在资源包中放置的 .png 文件的自定义粒子。发射器具有以下属性:
-
"trigger":指定发射器何时激活并产生粒子。可用值为:
"always" 始终激活,默认值
"walking" 移动时激活
"sprinting" 速度超过一定阈值时激活
"jumping" 在空中向上移动时激活
"falling" 在空中向下移动时激活
"gliding" 鞘翅飞行期间激活
"sneaking" 蹲下时激活
"swimming" 在水中时激活
"on_ground" 接触地面时激活
"in_air" 未接触地面时激活
"hurt" 受到伤害时激活
"on_fire" 着火时激活
-
"particle":指定发射器产生的粒子类型。可以是任何原版 Minecraft 粒子、其他已安装模组注册的粒子,或对于资源包中的完全自定义粒子,请使用 piscosmetics:cosmetic_particle。注意,所有自定义粒子均不受物理效果影响。
-
"rate":粒子生成之间的刻数间隔。
-
"spread":粒子的扩散范围。
-
"count":每次速率间隔内生成的粒子数量。
-
"offset_x"、"offset_y" 和 "offset_z":沿与对应外观字段相同的方向平移发射器。
-
"custom_size":自定义粒子的大小。
-
"lifetime":粒子持续的时间(单位:刻)。
-
"color":粒子颜色;仅适用于 "particle": "minecraft:entity_effect"。
-
"texture":资源包中自定义粒子 .png 的路径。仅在 "particle": "piscosmetics:cosmetic_particle" 时使用。
注意
指定资源位置时,请始终仅使用 your_namespace:filename,不要包含任何文件夹路径或后缀。
关键物品
Mega Showdown 和 Genesis Forms 的关键物品(如 Mega 石、mega 手镯、Z 手环、极巨腕带、太晶珠等)在佩戴时可显示为外观效果。物品功能保持不变。安装 Genesis Forms 后,其关键物品可佩戴于以下饰品槽位:手腕(mega_bracelet, mega_cuff, dynamax_band)、戒指(mega_ring, z_ring, z_power_ring, key_stone)、项链(mega_charm)和腰带(tera_orb)。
有两种方式为关键物品赋予外观:
"render_for":一个物品列表,表示此外观是这些物品的默认外观,例如 ["genesisforms:key_stone"]。佩戴在这些饰品槽位中的每个物品都会显示此外观,包括其 hide_armor 和 particle_emitters。此时 "slot" 仅用于选择默认位置。
- 针对单个物品:可以为单个物品赋予专属外观,该外观优先级高于
"render_for"。玩家通常通过蓝图实现,你也可以使用命令:
/give @s genesisforms:key_stone[custom_data={cosmetic:"your_namespace:golden_key_stone"}]
拥有专属外观的物品会在工具提示中显示该外观(Look: ...)。若要移除外观,请将物品单独放入磨刀石中。处理后物品恢复朴素状态,且不会返还任何材料。
蓝图
蓝图携带一个外观,并在锻造台中使用。空白蓝图由一张纸和青金石合成。每种外观的蓝图均位于 “Pi's Cosmetics” 创造模式标签页中,也可通过以下命令获取:
/give @s piscosmetics:cosmetic_blueprint[custom_data={blueprint:"your_namespace:my_cool_hat"}]
在锻造台中,将蓝图放入左侧槽位,右侧槽位留空。中间槽位放入的内容决定产出结果:
- 钻石:产出可穿戴的外观。
- 关键物品:产出带有该外观的关键物品。仅适用于具有
"key_items" 属性的外观,此类外观无法通过钻石制作。
- 空白蓝图:产出两张蓝图副本。不适用于不可复制的蓝图。
两个外观字段控制蓝图行为:
"key_items":将外观转换为关键物品外观,并指定其蓝图可应用于哪些类型的关键物品,可选值包括 "mega"、"z_move"、"dynamax" 和 "tera"。可以是单一类型或列表,如 ["mega", "tera"]。其他任何值均为错误,导致外观无法加载。
"copyable": false:阻止所有该外观的蓝图被复制。对于单个蓝图,可在其自定义数据中与 blueprint 一起添加 copyable:false。
服务器管理员须知
以上所有内容均可通过数据包进行修改:
data/piscosmetics/tags/item/blueprint_base.json:定义可穿戴外观的制作基底,默认为钻石。
data/piscosmetics/recipe/blank_blueprint.json:空白蓝图的合成配方。
data/piscosmetics/tags/item/key_items/<type>.json:定义哪些物品分别属于 mega、z_move、dynamax 和 tera 类关键物品。在此处添加你自己的 Genesis Forms 关键物品。
蓝图也可以通过原版的 set_custom_data 函数,利用战利品表进行发放。
资源包
你的资源包应按以下结构组织:
? your_resourcepack/
└── ? assets/
└── ? your_namespace/
├── ? geo/
│ └── ? item/
│ └── my_cool_hat.geo.json
│
├── ? textures/
│ └── ? item/
│ └── my_cool_hat.png
│ └── ? particle/
│ └── my_particle.png
│
└── ? animations/
└── my_cool_hat.animation.json
默认情况下,渲染器会处理透明/半透明纹理。
对于自发光纹理,只需添加一个后缀为 _emissive.png 的额外纹理文件即可。
模组将自动将其与同名纹理匹配,并根据自发光文件的透明度应用发光效果。
模型
所使用的模型必须采用 .geo.json 格式。建议你在 Blockbench 中将现有模型建模或转换为 Bedrock 实体,使用逐面 UV,并在最顶层设置单个骨骼。
通常良好的做法是将最顶层骨骼的原点设为 [0, 0, 0],以便轻松测试正确的偏移值。
示例:
{
"format_version": "1.12.0",
"minecraft:geometry": [
{
"description": {
"identifier": "geometry.test_cube",
"texture_width": 16,
"texture_height": 16
},
"bones": [
{
"name": "bone",
"pivot": [0, 0, 0],
"cubes": [
{
"origin": [-8, -8, 0],
"size": [16, 16, 1],
"uv": [0, 0]
}
]
}
]
}
]
}
纹理通常为 16x 或 32x,但理论上可以是任意尺寸,因为逐面 UV 支持这些尺寸。
动画的检测与应用方式类似于自发光纹理。
动态动画
渲染器能够根据玩家模型应用方向性动画切换。
其目的是模拟穿戴方向改变时软体的摆动效果。
这是在动画文件本身中设置的,通过创建如下命名的动画来实现:
idle(待机)
walk_forward(向前行走)
walk_backward(向后行走)
walk_left(向左行走)
walk_right(向右行走)
jump(跳跃)
fall(下落)
glide(滑翔)
滑翔动画切换可以与鞘翅隐藏以及滑翔时的粒子生成触发器配合使用,以创建带有拖尾效果的动画翅膀。
致谢
感谢以下人员:
Todredmi 激励我为 Fabric 平台改进此功能,并协助进行 bug 修复和截图工作。
Noowtie 最初引领我进入这一领域。
Puremask 提供了极具启发性的代码示例,尤其是针对服务端粒子渲染的部分。
Framework
This mod renders cosmetics physically on the player model, on Fabric and NeoForge for Minecraft 1.21.1. It works on
its own (vanilla armour slots), and also supports the Accessories mod,
Mega Showdown mod and Genesis Forms when they are installed, so that
items in all their slots can be rendered too. All three are optional; only GeckoLib (and Fabric API on Fabric) is required.
Rendering is done through a custom pipeline that uses Geckolib, allowing for animated
attachments and features of textures like transparency and emission.
The mod only contains generic items which can be cloned and overidden in many aspects with datapack JSONs
and an accompanying resourcepack.
This allows users to add their own custom cosmetics that are worn in any slot provided by Accessories and
Mega Showdown, and to give the key items of Mega Showdown and Genesis Forms their own looks.
Datapack
New items are effectively copies of existing generic items with NBT data. To override the appearance of
generic items, they must be specified in a datapack, structured as data/your_namespace/cosmetic/newitem.json.
Cosmetics use the universal cosmetic item, which goes in whatever slot the JSON's "slot" field says:
/give @s piscosmetics:cosmetic[custom_data={cosmetic:"your_namespace:my_cool_hat"}]
? your_datapack/
├── pack.mcmeta
├── pack.png
└── ? data/
└── ? your_namespace/
└── ? cosmetic/
├── my_cool_hat.json
├── special_sword.json
└── ...
The contents of the JSON file determine the various properties of the NBT tagged item. All fields except "slot" are
optional and will fall back onto default values if left empty.
The following fields are available:
{
"slot": "feet",
"name": "Dragon Boots",
"color": "gold",
"model": "your_namespace:cosmetic_feet",
"texture": "your_namespace:cosmetic_feet",
"animation": "your_namespace:cosmetic_feet",
"attach": "right_leg",
"translate_x": 0.1,
"translate_y": 0.2,
"translate_z": -0.1,
"rotate_x": 5.0,
"rotate_y": 10.0,
"rotate_z": 0.0,
"scale": 0.9,
"hide_armor": ["feet", "elytra"],
"icon": "your_namespace:item/cosmetic_feet",
"copyable": true,
"particle_emitters": [
{
"trigger": "walking",
"particle": "minecraft:end_rod",
"rate": 5,
"spread": 0.3,
"count": 2,
"offset_y": 0.1
},
{
"trigger": "sprinting",
"particle": "piscosmetics:cosmetic_particle",
"rate": 10,
"spread": 0.5,
"count": 1,
"offset_y": 0.5,
"custom_size": 0.5,
"lifetime": 20,
"texture": "your_namespace:lettera"
},
{
"trigger": "jumping",
"particle": "minecraft:entity_effect",
"rate": 3,
"spread": 1.0,
"count": 5,
"offset_y": 0.0,
"color": "#FF5500"
}
]
}
-
"slot": Specifies which inventory slot the cosmetic goes in; this can be either something from the Accessories API,
one of the Mega Showdown slots, or a vanilla armour slot. The available slots are:
-
Accessories slots
"hat"
"back"
"belt"
"cape"
"charm"
"face"
"hand"
"necklace"
"ring"
"shoes"
"wrist"
"anklet"
-
Mega Showdown slots
"dynamax_slot"
"mega_slot"
"tera_slot"
"z_slot"
-
Vanilla slots
"head"
"chest"
"legs"
"feet"
Accessories and Mega Showdown slots need those mods installed; the vanilla slots always work, and can also be
equipped by right-clicking like armour. A slot that doesn't exist on a server simply can't be equipped there. To use
a slot added by another mod or datapack, also add piscosmetics:cosmetic to that slot's item tag,
data/accessories/tags/item/<slot>.json.
-
"name": Display name for item in your inventory
-
"color": Colour of the name everywhere it shows, as a colour name like "gold" or a hex code like "#FF8800".
Names are aqua by default.
-
"model", "texture", "animation": The namespace and file name of your .geo.json model file, texture file, and
animation file. See the resourcepack section of this guide for information on how to format and place these files in the resourcepack.
-
"attach": which player bone it attaches to and moves with in all normal Minecraft body animations. Note that paired rendered slots, which are "shoes", "legs" and "feet"
cannot be overridden this way. Valid player bones are:
"head"
"body" or "chest"
"left_arm"
"right_arm"
"left_leg"
"right_leg"
-
Offsets:
"translate_x": Shifts cosmetic left (+) or right (-).
"translate_y": Shifts cosmetic up (+) or down (-).
"translate_z": Shifts cosmetic forwards (+) or backwards (-).
"rotate_x": Tilts cosmetic forwards (+) or backwards (-).
"rotate_y": Turns cosmetic left (+) or right (-).
"rotate_z": Rolls cosmetic left (+) or right (-).
"scale": Scales the cosmetic up or down in all dimensions. Note that this is an override value and is not added
to any hidden defaults, unlike other offset values.
-
"hide_armor": Specifies vanilla armour slot to not be rendered, in case it clips into your cosmetic. Can be a single
slot or a list like ["chest", "legs"]. "elytra" is a special value that specifically only disables the elytra rendering;
similarly, "chest" does not affect the elytra.
-
"icon": Overrides the in-hand and the dropped texture of the item with a .png file in the resourcepack. Not
including this field results in hand and ground renderer being the model of the cosmetic itself.
-
"copyable": Set to false so this cosmetic's blueprints can't be copied. See the blueprints section.
-
"key_items" and "render_for": Used for key item looks. See the key items section.
-
"particle_emitters": This is a complicated field that allows you to place as many particle emitters as you like (in a list) anchored
to the cosmetic. Each emitter can be fully customised, and supports custom particles derived from .png files you place
in the resourcepack. Emitters have the following properties:
-
"trigger": Specifies when the emitter is active and producing particles. Available values are:
"always" is always active, default
"walking" is active when you are moving
"sprinting" is active when you are moving past a certain speed
"jumping" is active when you are moving upwards in air
"falling" is active when you are moving downwards in air
"gliding" is active during elytra flight
"sneaking" is active when crouching
"swimming" is active when you are in water
"on_ground" is active when you are touching the ground
"in_air" is active when you are not touching the ground
"hurt" is active when you take damage
"on_fire" is active when you are burning
-
"particle": Specifies the type of particle produced by the emitter. This can be any vanilla minecraft particle, any
registered particles from other installed mods, or for fully custom particles in the resourcepack, use piscosmetics:cosmetic_particle.
Note that all custom particles are not affected by physics.
-
"rate": Number of ticks between particle spawns.
-
"spread": How much the particles spread out.
-
"count": How many particles are produced per rate.
-
"offset_x", "offset_y", and "offset_z" translate the emitters in the same direction as their equivalent cosmetic fields.
-
"custom_size": Size of a custom particle.
-
"lifetime": How long the particle lasts, in ticks.
-
"color": What colour the particle is; only works with "particle": "minecraft:entity_effect".
-
"texture": Path to the custom particle .png in the resourcepack. Only use this with "particle": "piscosmetics:cosmetic_particle".
Note
When specifying resource locations, always only use your_namespace:filename without any folder or suffixes.
Key Items
The key items of Mega Showdown and Genesis Forms (Key Stones, Mega Bracelets, Z-Rings, Dynamax Bands, Tera Orbs and so on)
can be drawn as cosmetics while worn. The item keeps working exactly as before. With Genesis Forms installed, its key items
can be worn in these Accessories slots: wrist (mega_bracelet, mega_cuff, dynamax_band), ring (mega_ring, z_ring, z_power_ring,
key_stone), necklace (mega_charm) and belt (tera_orb).
There are two ways to give a key item a look:
"render_for": A list of items this cosmetic is the default look for, e.g. ["genesisforms:key_stone"]. Every one of
those items worn in an Accessories slot shows this cosmetic, including its hide_armor and particle_emitters. "slot" then
only picks the default position.
- Per item: a single item can be given its own look, which wins over
"render_for". Players do this with blueprints, or you
can use a command:
/give @s genesisforms:key_stone[custom_data={cosmetic:"your_namespace:golden_key_stone"}]
An item with its own look shows it in the tooltip (Look: ...). To take the look off, put the item alone in a grindstone.
It comes out plain, and nothing is given back.
Blueprints
A blueprint carries one cosmetic and is used up in a smithing table. Blank blueprints are crafted from a paper and a lapis
lazuli. Every cosmetic's blueprint is in the "Pi's Cosmetics" creative tab, or can be given with:
/give @s piscosmetics:cosmetic_blueprint[custom_data={blueprint:"your_namespace:my_cool_hat"}]
In the smithing table, put the blueprint in the left slot and leave the right slot empty. What goes in the middle decides
what comes out:
- A diamond: the wearable cosmetic.
- A key item: that key item with the look. Only works for cosmetics with
"key_items", which can't be made from a diamond.
- A blank blueprint: two copies of the blueprint. Doesn't work for uncopyable blueprints.
Two cosmetic fields control blueprints:
"key_items": Turns the cosmetic into a key item look and picks which key items its blueprint goes on, any of "mega",
"z_move", "dynamax" and "tera". Can be a single type or a list like ["mega", "tera"]. Any other value is an error,
and the cosmetic won't load.
"copyable": false stops all of a cosmetic's blueprints from being copied. For a single blueprint, add copyable:false
to its custom data next to blueprint.
For server owners
All of these can be changed in a datapack:
data/piscosmetics/tags/item/blueprint_base.json: what wearable cosmetics are made from, a diamond by default.
data/piscosmetics/recipe/blank_blueprint.json: the recipe for blank blueprints.
data/piscosmetics/tags/item/key_items/<type>.json: which items count as mega, z_move, dynamax and tera key items.
Add your own Genesis Forms key items here.
Blueprints can also be handed out through loot tables with vanilla's set_custom_data function.
Resourcepack
Your resourcepack should be structured as follows:
? your_resourcepack/
└── ? assets/
└── ? your_namespace/
├── ? geo/
│ └── ? item/
│ └── my_cool_hat.geo.json
│
├── ? textures/
│ └── ? item/
│ └── my_cool_hat.png
│ └── ? particle/
│ └── my_particle.png
│
└── ? animations/
└── my_cool_hat.animation.json
By default, the renderer handles transparent/translucent textures.
For emissive textures, simply add another texture file suffixed with _emissive.png.
The mod will automatically match that to an identically named texture and apply the glow
based on the emissive file's transparency.
Models
Models used must be in the .geo.json format. It is recommended that you model or convert
an existing model in Blockbench to a Bedrock Entity with per-face UVs, with a single bone on the topmost level.
It is generally good practice to have the origin of the topmost bone be [0, 0, 0] for easy testing
of the correct offset values.
Example:
{
"format_version": "1.12.0",
"minecraft:geometry": [
{
"description": {
"identifier": "geometry.test_cube",
"texture_width": 16,
"texture_height": 16
},
"bones": [
{
"name": "bone",
"pivot": [0, 0, 0],
"cubes": [
{
"origin": [-8, -8, 0],
"size": [16, 16, 1],
"uv": [0, 0]
}
]
}
]
}
]
}
Textures are generally 16x or 32x, but can be any size theoretically as per-face UVs support them.
Animations are detected and applied in a similar manner as emissive textures.
Dynamic Animations
The renderer is capable of applying directional animation switches in accordance with the player model.
The idea is to simulate the swaying of soft bodies when the direction of the wearing changes
This is set up within the animation file itself, by creating animations named as follows:
idle
walk_forward
walk_backward
walk_left
walk_right
jump
fall
glide
The glide animation switch can be used in tandem with elytra hiding and particle generation trigger while gliding to create
animated wings with trailing effects.
Acknowledgements
Thank you to:
Todredmi for challenging me to evolve this for Fabric and for helping with the bugfixing process and screenshots.
Noowtie for sending me down this rabbit hole in the first place.
Puremask for providing very enlightening code samples, especially for serverside particle rendering.
评论 0
登录后参与评分
还没有评论,来抢沙发吧