实体资源包入门
资源包中的实体文件定义了构成实体视觉效果的各种资源引用，同时还包含这些视觉效果如何及何时被渲染的信息。
本文将逐项解析实体文件的各个组成部分。如需了解如何创建自定义实体的完整教程，请参阅我们的新手指南。
文件结构概览
{
"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
}
}
}虽然看起来复杂，但其中许多部分只是_短名定义_。短名定义是指我们将纹理路径或几何体标识符等资源分配给一个简短名称，后续可以通过这个短名进行引用。这样做的好处是：如果后期需要修改资源路径，只需在一处进行更改；同时也能让代码更加简洁，避免重复书写冗长的路径或标识符。
材质系统
材质决定了纹理的渲染方式。例如骷髅使用透明材质，末影人则使用让眼睛发光的材质。游戏内置了许多现成材质可供直接使用。
"materials": {
"default": "spider",
"invisible": "spider_invisible"
}这里定义了两种材质：spider和spider_invisible，对应的短名分别是default和invisible。注意这个键仅定义了短名与材质的对应关系，实体尚不知道何时使用哪种材质。
如需查看预设材质列表，请访问材质文档。若要学习创建自定义材质，可参考材质制作指南，但需注意这属于进阶内容。
纹理系统
纹理是映射到几何体上的图像。每个实体都有专属纹理。与材质类似，这个键也是短名定义，但此处引用的是纹理文件的路径。
"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"
}我们可以定义多个纹理变体，如上例中的蜜蜂就有四种状态纹理。通过分层纹理技术（如村民的生物群系基底与职业图层的组合）能实现更复杂效果。详情可参阅渲染控制器章节。
几何体
几何体文件通过骨骼系统定义实体外形。使用Blockbench等工具可以便捷创建模型，具体教程参见Blockbench指南。
"geometry": {
"default": "geometry.creeper",
"charged": "geometry.creeper.charged"
}短名对应的是几何体标识符：
{
"format_version" : "1.12.0",
"minecraft:geometry" : [
{
"description" : {
"identifier" : "geometry.creeper",
...
}
}
}如同高压爬行者有两种形态，实体也可以配置多套几何体。
TIP
当视觉效果异常时，请优先检查实体短名是否存在拼写错误。
渲染控制器
渲染控制器负责统筹材质、纹理和几何体的渲染逻辑，通过短名引用这些元素并定义渲染条件。
{
"format_version": "1.10.0",
"render_controllers": {
"controller.render.example": {
"geometry": "geometry.default",
"materials": [
{
"*": "material.default"
}
],
"textures": ["texture.default"]
}
}
}这个基础控制器始终使用默认材质组合。实际开发中可以实现动态切换纹理或隐藏骨骼等复杂功能，详见渲染控制器专题。
实体文件中通过标识符指定使用的控制器：
"render_controllers": [
"controller.render.example"
]一个可正常渲染的实体至少需要配置上述四个核心模块。
动画系统
动画控制实体的运动表现，包括行走、攻击或注视玩家等行为。动画通过代码描述骨骼运动轨迹，或使用数学公式驱动。注意动画必须绑定几何体才能生效。
{
"format_version" : "1.8.0",
"animations" : {
"animation.example.walk" : {...},
"animation.example.attack" : {...}
}
}每个动画都有独立标识符。实体文件中的动画键则是这些动画的短名映射：
"animations": {
"walk": "animation.example.walk",
"attack": "animation.example.attack",
"attack_controller": "controller.animation.example"
}其中attack_controller是动画控制器，用于管理动画过渡逻辑。建议通过[专题指南]了解控制器的结构设计。
重要提示
此键仅定义动画短名，并不会自动播放动画。若要使动画生效，必须通过脚本系统激活。
脚本系统
脚本系统用于在特定时机执行指令，包括运行动画、设置变量甚至控制实体尺寸。其中Molang是一种特殊的数学表达式语言，详见Molang专题。
"scripts": {
"initialize": [...],
"pre_animation": [...],
"animate": [...],
"scale": "1",
}Molang的核心要素包括：
- 查询语句（如
query.time_of_day获取游戏时间） - 自定义变量（如
variable.my_number存储数值） - 条件运算（如
q.time_of_day > v.my_number）
初始化脚本
当实体首次生成或重新加载时执行，适合设置变量初始值。
动画前处理
在每帧动画计算前运行，用于预处理动画所需变量。
动画控制器
在预处理后执行，是运行动画的核心区块：
"scripts": {
"animate": [
"attack_controller",
{
"walk": "q.modified_move_speed"
}
],
}这里attack_controller会逐帧更新动画状态，而walk动画的速度则与实体移动速度（q.modified_move_speed查询值）同步。若设为固定值如"walk":2，则动画会以双速播放。更复杂的控制逻辑可参考数学动画专题。
缩放控制
不同于行为包中的minecraft:scale组件（同时影响模型和碰撞箱），此处的缩放仅作用于视觉模型，且支持Molang表达式和分轴缩放：
"scripts": {
"scale": "q.variant",
"scaleX": 2,
"scaleY": 0.5
}通过随机函数可以实现环境实体的动态尺寸：
"scripts": {
"initialize": [
"v.scale = math.random_integer(1, 5);"
],
"scale": "v.scale"
}音效系统
音效短名定义后可用于动画事件触发，实现攻击连招等动态效果：
"sound_effects": {
"attack_1": "mob.entity.attack_1",
"attack_2": "mob.entity.attack_2",
"attack_3": "mob.entity.attack_3"
}注意动画中需使用短名，而命令中需使用sound_definitions.json定义的完整音效ID。
粒子系统
粒子效果通过短名定义后，可在动画中触发类似幻影翅膀特效等视觉效果：
"particle_effects": {
"smoke": "wiki:smoke_particle"
}刷怪蛋配置
通过此配置可生成对应实体的刷怪蛋，并自动加入创造模式物品栏。提供两种样式选择：
颜色模式：
"spawn_egg": {
"base_color": "#db7500",
"overlay_color": "#242222"
}贴图模式：
"spawn_egg": {
"texture": "wiki:example",
}若未配置此键，则不会生成刷怪蛋。
附加设置
enable_attachables：控制实体是否能装备武器等附件hide_armor：允许穿戴盔甲但不显示视觉效果
贡献者
