7.6 KiB
title, category, nav_order, tags, mentions
| title | category | nav_order | tags | mentions | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 实体资源包入门指南 | 基础 | 2 |
|
|
实体资源包入门指南
资源包中的实体文件定义了构成实体视觉效果的各种资源引用，同时包含了如何渲染这些视觉元素的详细逻辑。
本文将分解实体文件的每个组成部分并进行详细说明。如需创建自定义实体的完整指引，请参考我们的新手教程。
文件大纲
::: code-group
{
"format_version": "1.10.0",
"minecraft:client_entity": {
"description": {
"identifier": "wiki:example",
"materials": {...},
"textures": {...},
"geometry": {...},
"render_controllers": [...],
"animations": {...},
"scripts": {...},
"sound_effects": {...},
"particle_effects": {...},
"spawn_egg": {...},
"enable_attachables": false,
"hide_armor": false
}
}
}
:::
尽管看起来复杂，文件中大部分内容都采用简称定义模式。简称定义允许我们将资源路径（如材质纹理）或几何体ID等元素映射为简短名称以便后续引用。这种设计既方便后续资源路径变更时集中修改，也使代码保持简洁。
材质系统
材质（Materials）决定了纹理的渲染方式。例如骷髅使用透明材质，而末影人的眼睛材质具有自发光特性。大部分情况下可以直接使用预设材质而无需自定义。
::: code-group
"materials": {
"default": "spider",
"invisible": "spider_invisible"
}
:::
这里的default和invisible是简称，分别指向spider和spider_invisible材质。需要注意的是单纯的简称定义并不会告知实体何时使用不同材质。
纹理配置
纹理（Textures）是映射到模型表面的图像文件。此部分同样使用简称定义系统：
::: code-group
"textures": {
"default": "textures/entity/bee/bee",
"angry": "textures/entity/bee/bee_angry",
"nectar": "textures/entity/bee/bee_nectar",
"angry_nectar": "textures/entity/bee/bee_angry_nectar"
}
:::
支持定义多状态纹理（如蜜蜂的不同状态），也可叠加纹理层（参考村民的生物群系基底+职业层组合）。详细应用技巧参见渲染控制器章节。
几何体格式
几何体（Geometry）由Blockbench等建模工具生成的骨骼模型文件构成：
::: code-group
"geometry": {
"default": "geometry.creeper",
"charged": "geometry.creeper.charged"
}
:::
这里的简称指向几何体文件的唯一标识符（JSON文件中的identifier字段）。以苦力怕为例，充电与普通状态使用不同模型：
::: tip 模型显示异常时，首要检查简称定义是否存在拼写错误。 :::
渲染控制器
渲染控制器（Render Controllers）是控制实体渲染方式的核心组件，负责协调材质、纹理和模型的搭配使用：
::: code-group
{
"format_version": "1.10.0",
"render_controllers": {
"controller.render.example": {
"geometry": "geometry.default",
"materials": [{ "*": "material.default" }],
"textures": ["texture.default"]
}
}
}
:::
该示例始终使用"default"标识的各类资源。进阶用法可支持动态切换纹理与隐藏模型部件，详情参阅渲染控制器指南。
在实体文件中通过标识符指定渲染控制器：
::: code-group
"render_controllers": ["controller.render.example"]
:::
最低限度的实体文件须包含材质、纹理、几何体、渲染控制器四个基础模块。
动画系统
动画（Animations）定义模型骨骼的运动逻辑，涵盖行走、攻击、视线追踪等交互行为：
::: code-group
{
"format_version": "1.8.0",
"animations": {
"animation.example.walk": {...},
"animation.example.attack": {...}
}
}
:::
实体文件中需配置动画简称以便调用：
::: code-group
"animations": {
"walk": "animation.example.walk",
"attack": "animation.example.attack",
"attack_controller": "controller.animation.example"
}
:::
::: warning 重要提示 单单定义动画简称并不能启动动画，需通过脚本系统主动调用。 :::
脚本逻辑
脚本（Scripts）通过Molang表达式协调动画播放、变量设置、模型缩放等动态行为：
::: code-group
"scripts": {
"initialize": [...],
"pre_animation": [...],
"animate": [...],
"scale": "1"
}
:::
初始化脚本
实体生成或加载时执行，适合设置初始变量。
预动画脚本
每帧渲染前运行，用于计算动画参数。
动画脚本
每帧执行动画控制器和播放逻辑：
::: code-group
"animate": [
"attack_controller",
{ "walk": "q.modified_move_speed" }
]
:::
q.modified_move_speed将行走速度映射为动画播放速率。数值2表示双倍播放，动态公式使动画与实体速度保持同步。
模型缩放
scale参数支持通过Molang表达式调整模型尺寸：
::: code-group
"scripts": {
"scale": "q.variant",
"scaleX": 2,
"scaleY": 0.5
}
:::
该示例：
- Y轴方向缩放0.5倍
- X轴放大2倍
- 整体尺寸由变体值决定（
minecraft:variant组件）
::: tip 随机尺寸案例
math.random_integer(1,5)可在初始化时生成1-5的随机缩放系数。
:::
音效配置
音效简称便于在动画事件中调用：
::: code-group
"sound_effects": {
"attack_1": "mob.entity.attack_1",
"attack_2": "mob.entity.attack_2",
"attack_3": "mob.entity.attack_3"
}
:::
粒子系统
粒子简称用于动画事件触发：
::: code-group
"particle_effects": {
"smoke": "wiki:smoke_particle"
}
:::
生成蛋设置
生成蛋（Spawn Egg）支持纯色或自定义纹理两种风格：
::: code-group 纯色风格
"spawn_egg": {
"base_color": "#db7500",
"overlay_color": "#242222"
}
:::
::: code-group 定制纹理
"spawn_egg": {
"texture": "wiki.example"
}
:::
特殊参数
enable_attachables（启用配件）：控制实体能否持握工具hide_armor（隐藏护甲）：允许穿装备但不显示外观