添加了部分来自于BedrockWiki的文章！
This commit is contained in:
boybook
273
docs/wiki/3-实体/1-基础/entity-events.md
Normal file
273
docs/wiki/3-实体/1-基础/entity-events.md
Normal file
@@ -0,0 +1,273 @@
|
||||
---
|
||||
title: 实体事件
|
||||
category: 综合
|
||||
mentions:
|
||||
- ChibiMango
|
||||
- SirLich
|
||||
- Joelant05
|
||||
- MedicalJewel105
|
||||
- aexer0e
|
||||
- SmokeyStack
|
||||
- ThomasOrs
|
||||
tags:
|
||||
- 新手
|
||||
---
|
||||
|
||||
# 实体事件
|
||||
|
||||
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
|
||||
|
||||
实体事件是行为系统中与组件（Component）和组件组（Component Group）并列的基础构建模块之一。它们作为组件组的控制中枢，可以通过组件、动画（Animation）、动画控制器（Animation Controller）及其他事件进行调用。本文旨在详解实体内部及跨实体事件调用的方法，以及事件的基本格式结构。
|
||||
|
||||
## 事件结构
|
||||
|
||||
事件允许我们在特定条件满足时，通过添加或移除组件组来改变实体的行为模式。我们称之为"事件（Event）"，因为它们可以被战斗倒计时结束、玩家交互、环境变化等情景所触发。当事件激活时，会根据预定义指令处理组件组的增删操作。
|
||||
|
||||
每个事件可包含七个核心指令键，分别用于执行组件组增删、条件判断、事件触发及属性设置：
|
||||
- add（添加）
|
||||
- remove（移除）
|
||||
- randomize（随机化）
|
||||
- sequence（序列）
|
||||
- filters（过滤器）
|
||||
- trigger（触发器）
|
||||
- set_property（属性设置）
|
||||
|
||||
### 添加/移除
|
||||
|
||||
事件最基础的功能是通过add/remove键直接增删组件组。如下示例中的`wiki:ranged_attacker`事件：
|
||||
|
||||
::: code-group
|
||||
```json [示例]
|
||||
"wiki:ranged_attacker":{
|
||||
"add":{
|
||||
"component_groups":[
|
||||
"attacker",
|
||||
"ranged"
|
||||
]
|
||||
},
|
||||
"remove":{
|
||||
"component_groups":[
|
||||
"standby",
|
||||
"melee"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
:::tip 组件覆盖规则
|
||||
当添加组件组时，若现有活跃组件组中已包含同名组件，后添加的组件组会覆盖原有组件。
|
||||
:::
|
||||
|
||||
### 随机化
|
||||
|
||||
randomize参数允许根据权重概率随机执行组件组操作。原版牛的生成事件即使用该机制，实现95%概率生成成年牛，5%概率生成幼崽：
|
||||
|
||||
::: code-group
|
||||
```json [牛生成逻辑]
|
||||
"minecraft:entity_spawned":{
|
||||
"randomize":[
|
||||
{
|
||||
"weight":95,
|
||||
"add":{
|
||||
"component_groups":[
|
||||
"minecraft:cow_adult"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"weight":5,
|
||||
"add":{
|
||||
"component_groups":[
|
||||
"minecraft:cow_baby"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
:::warning 注意
|
||||
随机化配置中对每组权重进行归一化处理，最终不同选项的选择概率与其权重值占总权重的比例相关。
|
||||
:::
|
||||
|
||||
### 序列/过滤器
|
||||
|
||||
通过sequence参数可实现条件分支逻辑。原版僵尸的溺水转换事件根据是否是幼体执行不同操作：
|
||||
|
||||
::: code-group
|
||||
```json [僵尸溺水转换]
|
||||
"minecraft:convert_to_drowned":{
|
||||
"sequence":[
|
||||
{
|
||||
"filters":{
|
||||
"test":"has_component",
|
||||
"operator":"!=",
|
||||
"value":"minecraft:is_baby"
|
||||
},
|
||||
"add":["minecraft:convert_to_drowned"],
|
||||
"remove":["minecraft:start_drowned_transformation"]
|
||||
},
|
||||
{
|
||||
"filters":{
|
||||
"test":"has_component",
|
||||
"value":"minecraft:is_baby"
|
||||
},
|
||||
"add":["minecraft:convert_to_baby_drowned"],
|
||||
"remove":["minecraft:start_drowned_transformation"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
:::tip 序列执行机制
|
||||
序列中的每个分支会依次检查执行，通过过滤器的分支都会被执行而无互斥性。若无过滤器则默认执行，但不影响后续分支的判断。
|
||||
:::
|
||||
|
||||
下面这个整合多条件的攻击序列示例展示了复杂逻辑的实现：
|
||||
|
||||
::: spoiler title="复杂攻击序列示例"
|
||||
|
||||
::: code-group
|
||||
```json [攻击逻辑]
|
||||
"wiki:on_hit":{
|
||||
"randomize":[
|
||||
{
|
||||
"weight":60 //60%概率无操作
|
||||
},
|
||||
{
|
||||
"weight":40,
|
||||
"sequence":[
|
||||
{"trigger":"attack_event"},
|
||||
{
|
||||
"filters":["!minecraft:is_sheared"],
|
||||
"sequence":[...]
|
||||
},
|
||||
{
|
||||
"filters":["minecraft:is_sheared"],
|
||||
"sequence":[...]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
:::
|
||||
:::
|
||||
|
||||
### 事件触发
|
||||
|
||||
通过trigger参数可以在事件中调用其他事件，结合target参数可实现跨实体交互。以玩家与猪互动事件为例：
|
||||
|
||||
::: code-group
|
||||
```json [互动事件]
|
||||
"wiki:on_interact": {
|
||||
"trigger": {
|
||||
"filters":{
|
||||
"test":"is_family",
|
||||
"subject":"self",
|
||||
"value":"pig"
|
||||
},
|
||||
"event":"wiki:interacted",
|
||||
"target":"other"
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
:::tip 目标上下文
|
||||
事件的执行需要明确的实体上下文。例如互动事件中，"other"指代互动发起者。若无对应上下文时，"target"指令将失效。
|
||||
:::
|
||||
|
||||
## 事件调用方式
|
||||
|
||||
事件可通过以下五种途径触发：
|
||||
1. 组件系统调用（如环境传感器）
|
||||
2. 动画时间轴调用
|
||||
3. 动画控制器状态切换
|
||||
4. 其他事件链式调用
|
||||
5. 控制台命令 `/event`
|
||||
|
||||
以下示例展示不同调用方式：
|
||||
|
||||
### 组件系统调用
|
||||
|
||||
僵尸的水下转换事件通过环境传感器触发：
|
||||
|
||||
::: code-group
|
||||
```json [僵尸转换]
|
||||
"minecraft:environment_sensor": {
|
||||
"triggers": {
|
||||
"filters":["is_underwater"],
|
||||
"event":"minecraft:start_transforming"
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 动画调用
|
||||
|
||||
在动画时间轴中按时间节点触发扑击事件：
|
||||
|
||||
::: code-group
|
||||
```json [动画事件]
|
||||
"animation.entity.pounce_timer": {
|
||||
"timeline": {
|
||||
"10.0": "@s wiki:start_pouncing"
|
||||
},
|
||||
"animation_length":10.1
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 跨实体事件调用
|
||||
|
||||
唤魔者的特殊技能通过发送事件到特定实体：
|
||||
|
||||
::: code-group
|
||||
```json [唤魔者技能]
|
||||
"minecraft:behavior.send_event":{
|
||||
"event_choices":[{
|
||||
"filters":["is_family:sheep"],
|
||||
"sequence":[{
|
||||
"event":"wololo",
|
||||
"target":"other"
|
||||
}]
|
||||
}]
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 内置事件
|
||||
|
||||
系统级自动触发事件需特别注意：
|
||||
|
||||
| 事件名称 | 触发条件 |
|
||||
|------------------------------|--------------------------|
|
||||
| minecraft:entity_spawned | 实体生成时 |
|
||||
| minecraft:entity_born | 繁殖产生新实体时 |
|
||||
| minecraft:entity_transformed | 实体形态转换完成时 |
|
||||
| minecraft:on_prime | 爆炸物引信燃尽准备爆炸时 |
|
||||
|
||||
::: code-group
|
||||
```json [牛实体配置示例]
|
||||
"events": {
|
||||
"minecraft:entity_spawned": {
|
||||
"randomize":[
|
||||
{"weight":95, "add":["minecraft:cow_adult"]},
|
||||
{"weight":5, "add":["minecraft:cow_baby"]}
|
||||
]
|
||||
},
|
||||
"minecraft:entity_born":{
|
||||
"add":["minecraft:cow_baby"]
|
||||
},
|
||||
"minecraft:entity_transformed":{
|
||||
"add":["minecraft:cow_adult"]
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
通过合理组合这些功能模块，开发者可以创建出丰富复杂的实体行为逻辑。建议配合动画控制器文档以构建更高级的行为系统。
|
||||
178
docs/wiki/3-实体/1-基础/entity-intro-bp.md
Normal file
178
docs/wiki/3-实体/1-基础/entity-intro-bp.md
Normal file
@@ -0,0 +1,178 @@
|
||||
---
|
||||
title: 实体行为包入门指南
|
||||
category: 基础知识
|
||||
nav_order: 1
|
||||
tags:
|
||||
- 指南
|
||||
- 新手入门
|
||||
mentions:
|
||||
- SirLich
|
||||
- solvedDev
|
||||
- stirante
|
||||
- Joelant05
|
||||
- destruc7ion
|
||||
- MedicalJewel105
|
||||
- ChibiMango
|
||||
- SmokeyStack
|
||||
- ThomasOrs
|
||||
---
|
||||
|
||||
# 实体行为包入门指南
|
||||
|
||||
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
|
||||
|
||||
构成行为包实体文件基础的三个主要结构如下：本文将解释它们的含义及使用方法。
|
||||
|
||||
组件组（component group）与组件（components）的混淆是常见的错误来源，请特别注意区分两者的区别。
|
||||
|
||||
## 组件（Components）
|
||||
|
||||
组件是构成Minecraft实体的逻辑构建模块。所有组件均由Mojang开发并提供给开发者使用。组件可实现多种功能，例如设置实体尺寸或赋予游泳能力等。完整组件列表可参考[官方文档](https://bedrock.dev/docs/stable/Entities)。
|
||||
|
||||
_无法_创建自定义组件。所有组件列表由微软硬编码实现并对外提供。
|
||||
|
||||
需要为实体添加行为时，可通过在`minecraft:entity`对象的`components`属性中插入组件。例如要给实体添加攀爬能力，可插入组件：`"minecraft:can_climb": {}`。
|
||||
|
||||
组件统一采用`"minecraft:<组件名称>": { <参数设置> }`格式。不同类型组件需要设置不同参数。
|
||||
|
||||
以下是实体内的组件应用范例：
|
||||
|
||||
::: code-group
|
||||
```json [BP/entities/example.json#minecraft:entity]
|
||||
"components": {
|
||||
"minecraft:type_family": {
|
||||
"family": [
|
||||
"player"
|
||||
]
|
||||
},
|
||||
"minecraft:collision_box": {
|
||||
"width": 0.6,
|
||||
"height": 1.8
|
||||
},
|
||||
"minecraft:can_climb": {},
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
（注意`components`列表_仅_包含组件）
|
||||
|
||||
## 组件组（Component Groups）
|
||||
|
||||
组件组用于整理归类多个组件。通过`事件（events）`可动态添加或移除组件组，从而实现定制化游戏玩法。
|
||||
|
||||
应用示例：
|
||||
|
||||
::: code-group
|
||||
```json [BP/entities/example.json#minecraft:entity]
|
||||
"component_groups": {
|
||||
|
||||
//组件组名称
|
||||
"minecraft:cat_persian": {
|
||||
|
||||
//合法的组件列表（可添加多项）
|
||||
"minecraft:variant": {
|
||||
"value": 6
|
||||
},
|
||||
"minecraft:physics": {}
|
||||
},
|
||||
|
||||
//第二个组件组名称
|
||||
"wiki:example_group": {
|
||||
"minecraft:type_family": {
|
||||
"family": [
|
||||
"wiki_is_awesome!"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
所有组件组均为自定义创建，不可直接引用其他实体的组件组。
|
||||
|
||||
在原版Minecraft实体中，组件组使用`minecraft:`前缀命名（如示例中的`minecraft:cat_persian`）。但需特别注意这些_并非_组件。开发者可自由使用任意命名规则，例如上文中的`wiki:example_group`。更多命名空间信息请参阅[此文档](/concepts/namespaces)。
|
||||
|
||||
放在组件组中的组件不会自动生效，必须通过事件激活才能影响实体行为。多个组件组可同时生效。
|
||||
|
||||
## 事件（Events）
|
||||
|
||||
事件是一种特殊语法，用于在满足条件时通过组件触发添加/移除组件组的操作，从而实现实体的动态行为。
|
||||
|
||||
示例结构：
|
||||
|
||||
::: code-group
|
||||
```json [BP/entities/example.json#minecraft:entity#events]
|
||||
"minecraft:ageable_grow_up": { //事件名称
|
||||
"remove": { //需要移除的组件组列表
|
||||
"component_groups": [
|
||||
"minecraft:cat_baby"
|
||||
]
|
||||
},
|
||||
"add": {
|
||||
"component_groups": [
|
||||
"minecraft:cat_adult" //需要添加的组件组列表
|
||||
]
|
||||
}
|
||||
},
|
||||
```
|
||||
:::
|
||||
|
||||
事件与组件组相同，均为完全自定义内容。不可直接照搬其他实体的事件名称（例如`"minecraft:ageable_grow_up"`）。若需类似功能，应自主设计组件组和事件。
|
||||
|
||||
_仅能对组件组进行添加/移除操作_，无法直接操作单个组件。
|
||||
|
||||
当满足某些条件时，特定组件会触发事件。下方示例演示交互功能实现：
|
||||
|
||||
::: code-group
|
||||
```json [BP/entities/example.json#minecraft:entity]
|
||||
"components": {
|
||||
"minecraft:interact": {
|
||||
"interactions": [
|
||||
{
|
||||
"on_interact": {
|
||||
"filters": [ //触发条件筛选器
|
||||
{
|
||||
"test":"is_family",
|
||||
"subject": "other",
|
||||
"value": "player" //被交互对象属于玩家
|
||||
}
|
||||
],
|
||||
"target": "self", //作用目标为实体自身
|
||||
"event": "wiki:on_interact" //触发指定事件
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"component_groups": {
|
||||
"wiki:interacted": {
|
||||
"minecraft:scale": { //缩放组件
|
||||
"value": 2
|
||||
}
|
||||
}
|
||||
},
|
||||
"events":{
|
||||
"wiki:on_interact":{ //事件定义
|
||||
"add": {
|
||||
"component_groups": [ "wiki:interacted" ] //添加组件组
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
当玩家与该实体交互时，将触发`"wiki:on_interact"`事件，添加`"wiki:interacted"`组件组，从而激活缩放效果。
|
||||
|
||||
想深入了解事件的更多用法，请参阅[实体事件](/entities/entity-events)页面。
|
||||
|
||||
<BButton link="/entities/entity-events">实体事件详解</BButton>
|
||||
|
||||
## 原版应用案例
|
||||
|
||||
组件组与事件是原版实体实现自定义行为的核心工具。以下列举部分原版特性应用：
|
||||
|
||||
- 僵尸在水下停留过久后会通过事件转变为溺尸（drowned）
|
||||
|
||||
- 狐狸根据生成环境的不同，采用`minecraft:fox_red`与`minecraft:fox_active`组件组实现毛色变化
|
||||
|
||||
- 末影人使用事件机制实现被注视时进行攻击
|
||||
273
docs/wiki/3-实体/1-基础/entity-intro-rp.md
Normal file
273
docs/wiki/3-实体/1-基础/entity-intro-rp.md
Normal file
@@ -0,0 +1,273 @@
|
||||
---
|
||||
title: 实体资源包入门指南
|
||||
category: 基础指南
|
||||
nav_order: 2
|
||||
tags:
|
||||
- 新手教程
|
||||
- 入门指南
|
||||
mentions:
|
||||
- SirLich
|
||||
- MedicalJewel105
|
||||
- Overload1252
|
||||
- ChibiMango
|
||||
- Luthorius
|
||||
- TheItsNameless
|
||||
- SmokeyStack
|
||||
- ThomasOrs
|
||||
---
|
||||
|
||||
# 实体资源包入门指南
|
||||
|
||||
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
|
||||
|
||||
资源包中的实体文件定义了构成实体视觉效果的各种资源引用，同时包含了如何渲染这些视觉元素的详细逻辑。
|
||||
|
||||
本文将分解实体文件的每个组成部分并进行详细说明。如需创建自定义实体的完整指引，请参考我们的[新手教程](/guide/custom-entity)。
|
||||
|
||||
## 文件大纲
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/example.json]
|
||||
{
|
||||
"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
|
||||
```json [RP/entity/spider.entity.json#minecraft:client_entity/description]
|
||||
"materials": {
|
||||
"default": "spider",
|
||||
"invisible": "spider_invisible"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
这里的`default`和`invisible`是简称，分别指向`spider`和`spider_invisible`材质。需要注意的是单纯的简称定义并不会告知实体何时使用不同材质。
|
||||
|
||||
[预置材质列表](/documentation/materials)可供参考。[自定义材质教程](/visuals/materials)适合进阶开发者。
|
||||
|
||||
## 纹理配置
|
||||
纹理（Textures）是映射到模型表面的图像文件。此部分同样使用简称定义系统：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/bee.entity.json#minecraft:client_entity/description]
|
||||
"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"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
支持定义多状态纹理（如蜜蜂的不同状态），也可叠加纹理层（参考村民的生物群系基底+职业层组合）。详细应用技巧参见[渲染控制器章节](/entities/render-controllers)。
|
||||
|
||||
## 几何体格式
|
||||
几何体（Geometry）由Blockbench等建模工具生成的骨骼模型文件构成：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/creeper.entity.json#minecraft:client_entity/description]
|
||||
"geometry": {
|
||||
"default": "geometry.creeper",
|
||||
"charged": "geometry.creeper.charged"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
这里的简称指向几何体文件的唯一标识符（JSON文件中的`identifier`字段）。以苦力怕为例，充电与普通状态使用不同模型：
|
||||
|
||||
::: tip
|
||||
模型显示异常时，首要检查简称定义是否存在拼写错误。
|
||||
:::
|
||||
|
||||
## 渲染控制器
|
||||
渲染控制器（Render Controllers）是控制实体渲染方式的核心组件，负责协调材质、纹理和模型的搭配使用：
|
||||
|
||||
::: code-group
|
||||
```json [RP/render_controllers/example.rc.json]
|
||||
{
|
||||
"format_version": "1.10.0",
|
||||
"render_controllers": {
|
||||
"controller.render.example": {
|
||||
"geometry": "geometry.default",
|
||||
"materials": [{ "*": "material.default" }],
|
||||
"textures": ["texture.default"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
该示例始终使用"default"标识的各类资源。进阶用法可支持动态切换纹理与隐藏模型部件，详情参阅[渲染控制器指南](/entities/render-controllers)。
|
||||
|
||||
在实体文件中通过标识符指定渲染控制器：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/example.json#minecraft:client_entity/description]
|
||||
"render_controllers": ["controller.render.example"]
|
||||
```
|
||||
:::
|
||||
|
||||
最低限度的实体文件须包含材质、纹理、几何体、渲染控制器四个基础模块。
|
||||
|
||||
## 动画系统
|
||||
动画（Animations）定义模型骨骼的运动逻辑，涵盖行走、攻击、视线追踪等交互行为：
|
||||
|
||||
::: code-group
|
||||
```json [RP/animations/example.a.json]
|
||||
{
|
||||
"format_version": "1.8.0",
|
||||
"animations": {
|
||||
"animation.example.walk": {...},
|
||||
"animation.example.attack": {...}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
实体文件中需配置动画简称以便调用：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/example.json#minecraft:client_entity/description]
|
||||
"animations": {
|
||||
"walk": "animation.example.walk",
|
||||
"attack": "animation.example.attack",
|
||||
"attack_controller": "controller.animation.example"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
::: warning 重要提示
|
||||
单单定义动画简称并不能启动动画，需通过脚本系统主动调用。
|
||||
:::
|
||||
|
||||
## 脚本逻辑
|
||||
脚本（Scripts）通过Molang表达式协调动画播放、变量设置、模型缩放等动态行为：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/example.json#minecraft:client_entity/description]
|
||||
"scripts": {
|
||||
"initialize": [...],
|
||||
"pre_animation": [...],
|
||||
"animate": [...],
|
||||
"scale": "1"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 初始化脚本
|
||||
实体生成或加载时执行，适合设置初始变量。
|
||||
|
||||
### 预动画脚本
|
||||
每帧渲染前运行，用于计算动画参数。
|
||||
|
||||
### 动画脚本
|
||||
每帧执行动画控制器和播放逻辑：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/example.json#minecraft:client_entity/description]
|
||||
"animate": [
|
||||
"attack_controller",
|
||||
{ "walk": "q.modified_move_speed" }
|
||||
]
|
||||
```
|
||||
:::
|
||||
|
||||
`q.modified_move_speed`将行走速度映射为动画播放速率。数值`2`表示双倍播放，动态公式使动画与实体速度保持同步。
|
||||
|
||||
### 模型缩放
|
||||
`scale`参数支持通过Molang表达式调整模型尺寸：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/example.json#minecraft:client_entity/description]
|
||||
"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
|
||||
```json [RP/entity/example.json#minecraft:client_entity/description]
|
||||
"sound_effects": {
|
||||
"attack_1": "mob.entity.attack_1",
|
||||
"attack_2": "mob.entity.attack_2",
|
||||
"attack_3": "mob.entity.attack_3"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
## 粒子系统
|
||||
粒子简称用于动画事件触发：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/example.json#minecraft:client_entity/description]
|
||||
"particle_effects": {
|
||||
"smoke": "wiki:smoke_particle"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
[自定义粒子教程](/particles/particles) | [动画效果应用](/visuals/animation-effects)
|
||||
|
||||
## 生成蛋设置
|
||||
生成蛋（Spawn Egg）支持纯色或自定义纹理两种风格：
|
||||
|
||||
::: code-group 纯色风格
|
||||
```json [RP/entity/example.json#minecraft:client_entity/description]
|
||||
"spawn_egg": {
|
||||
"base_color": "#db7500",
|
||||
"overlay_color": "#242222"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
::: code-group 定制纹理
|
||||
```json [RP/entity/example.json#minecraft:client_entity/description]
|
||||
"spawn_egg": {
|
||||
"texture": "wiki.example"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
## 特殊参数
|
||||
- `enable_attachables`（启用配件）：控制实体能否持握工具
|
||||
- `hide_armor`（隐藏护甲）：允许穿装备但不显示外观
|
||||
236
docs/wiki/3-实体/1-基础/entity-properties.md
Normal file
236
docs/wiki/3-实体/1-基础/entity-properties.md
Normal file
@@ -0,0 +1,236 @@
|
||||
---
|
||||
title: 实体属性
|
||||
category: 常规
|
||||
tags:
|
||||
- 实验性
|
||||
mentions:
|
||||
- SirLich
|
||||
- sermah
|
||||
- MedicalJewel105
|
||||
- Luthorius
|
||||
- stirante
|
||||
- TheItsNameless
|
||||
---
|
||||
|
||||
# 实体属性
|
||||
|
||||
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
|
||||
|
||||
:::warning
|
||||
本文档包含过时信息及实验性内容。如需最新稳定版信息，请查阅[微软官方文档](https://learn.microsoft.com/en-us/minecraft/creator/documents/introductiontoentityproperties)。
|
||||
:::
|
||||
|
||||
本文档介绍在Minecraft基岩版1.16.230.52测试版中加入的新实体属性系统（又称Actor Properties）。实体属性的实现目的是在实体服务端（行为包）高效保存数据或存储数值，无需使用组件或属性（例如"minecraft:variant"），其运作原理类似方块属性。
|
||||
|
||||
## 实体属性定义
|
||||
|
||||
### 定义实体属性
|
||||
|
||||
实体属性定义示例：
|
||||
|
||||
::: code-group
|
||||
```json [实体定义]
|
||||
{
|
||||
"minecraft:entity":{
|
||||
"description":{
|
||||
"identifier":"entity:properties_example",
|
||||
"properties":{
|
||||
"property:number_range_example":{
|
||||
"values":{
|
||||
"min":0,
|
||||
"max":100
|
||||
}
|
||||
},
|
||||
"property:number_enum_example":{
|
||||
"values":[
|
||||
1,
|
||||
2
|
||||
]
|
||||
},
|
||||
"property:string_enum_example":{
|
||||
"values":[
|
||||
"first",
|
||||
"second",
|
||||
"third"
|
||||
]
|
||||
},
|
||||
"property:boolean_enum_example":{
|
||||
"values":[
|
||||
true,
|
||||
false
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 实体属性字段说明
|
||||
|
||||
#### `values`
|
||||
|
||||
:::warning
|
||||
`values`字段为必填项，缺失此字段可能导致属性注册失败。
|
||||
:::
|
||||
|
||||
`values`字段可接受枚举值数组或数值区间（注意当前版本中整数、浮点和布尔枚举最多支持两个值）：
|
||||
|
||||
::: code-group
|
||||
```json [数值范围模式]
|
||||
"property:range_example": {
|
||||
"values": {
|
||||
"min": 0,
|
||||
"max": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json [枚举模式]
|
||||
"property:enum_example":{
|
||||
"values":[
|
||||
1,
|
||||
2
|
||||
]
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
#### `default`
|
||||
|
||||
可通过属性对象内的`default`字段设置属性默认值（默认使用枚举数组的第一个元素）：
|
||||
|
||||
::: code-group
|
||||
```json [默认值设置]
|
||||
"property:default_value_example":{
|
||||
"values":[
|
||||
true,
|
||||
false
|
||||
],
|
||||
"default":false
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
如示例所示，当实体生成时该属性会默认为`false`而非`true`。
|
||||
|
||||
#### `client_sync`
|
||||
|
||||
通过设置`client_sync`字段为`true`，可将属性同步到客户端资源包（Resource Pack）使用。默认值为`false`。
|
||||
|
||||
::: code-group
|
||||
```json [客户端同步示例]
|
||||
"property:client_sync_example": {
|
||||
"values": {
|
||||
"min": 0,
|
||||
"max": 20
|
||||
},
|
||||
"client_sync": true
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 操作与访问实体属性
|
||||
|
||||
可通过以下Molang查询访问实体属性：
|
||||
- `q.actor_property`
|
||||
- `q.has_actor_property`
|
||||
|
||||
:::warning
|
||||
这些Molang查询属于实验性功能
|
||||
:::
|
||||
|
||||
可通过`set_actor_property`事件响应设置实体属性值：
|
||||
|
||||
::: code-group
|
||||
```json [事件响应示例]
|
||||
"events":{
|
||||
"event:set_entity_property":{
|
||||
"set_actor_property":{
|
||||
"property:number_enum_example":2,
|
||||
"property:string_enum_example":"'second'",
|
||||
"property:boolean_enum_example":"!q.actor_property('property:boolean_enum_example')"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
## 实体别名系统
|
||||
|
||||
可通过定义实体别名（aliases），在`summon`指令中调用自定义标识符生成带预置属性的实体：
|
||||
|
||||
::: code-group
|
||||
```json [别名定义]
|
||||
{
|
||||
"format_version": "1.16.0",
|
||||
"minecraft:entity": {
|
||||
"description": {
|
||||
"identifier": "entity:properties_example",
|
||||
"is_spawnable": true,
|
||||
"is_summonable": true,
|
||||
"is_experimental": false,
|
||||
"properties": {
|
||||
"property:property_index": {
|
||||
"client_sync": true,
|
||||
"values": {
|
||||
"min": 0,
|
||||
"max": 2
|
||||
},
|
||||
"default": 0
|
||||
}
|
||||
},
|
||||
"aliases": {
|
||||
"entity:default_alias": {},
|
||||
"entity:first_alias": {
|
||||
"property:property_index": 1
|
||||
},
|
||||
"entity:second_alias": {
|
||||
"property:property_index": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
现在通过`/summon entity:first_alias`指令可生成带有`property:property_index=1`属性的实体。
|
||||
|
||||
## 实体动态组件
|
||||
|
||||
实体动态组件（Entity Permutations）可根据属性条件在每个Tick动态应用组件集合。需在`minecraft:entity`对象内与`components`同级添加`permutations`数组：
|
||||
|
||||
::: code-group
|
||||
```json [动态组件示例]
|
||||
"permutations":[
|
||||
{
|
||||
"condition":"q.actor_property('property:string_enum_example') == 'first'",
|
||||
"components":{
|
||||
"minecraft:scale":{
|
||||
"value":1.0
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"condition":"q.actor_property('property:string_enum_example') == 'second'",
|
||||
"components":{
|
||||
"minecraft:scale":{
|
||||
"value":2.0
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"condition":"q.actor_property('property:string_enum_example') == 'third'",
|
||||
"components":{
|
||||
"minecraft:scale":{
|
||||
"value":3.0
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
:::
|
||||
|
||||
当`property:string_enum_example`属性为"first"时，实体会应用1倍缩放，为"second"时应用2倍缩放，为"third"时则应用3倍缩放。
|
||||
337
docs/wiki/3-实体/1-基础/npc-dialogs.md
Normal file
337
docs/wiki/3-实体/1-基础/npc-dialogs.md
Normal file
@@ -0,0 +1,337 @@
|
||||
---
|
||||
title: NPC 对话框
|
||||
category: 通用
|
||||
tags:
|
||||
- 中级
|
||||
参与贡献:
|
||||
- kyleplo
|
||||
- StuartDA
|
||||
- MedicalJewel105
|
||||
- SirLich
|
||||
- solvedDev
|
||||
- omuhu
|
||||
- Sprunkles137
|
||||
- ThomasOrs
|
||||
---
|
||||
|
||||
# NPC 对话框
|
||||
|
||||
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
|
||||
|
||||
非玩家角色（NPC）是类似村民的实体，可通过对话框显示消息并提供多个交互按钮。最初设计用于冒险地图，随着 `/dialogue` 命令的引入，现在也能在常规附加包中使用。
|
||||
|
||||
## 对话框文件
|
||||
|
||||
NPC 对话数据存储于行为包根目录下 `dialogue` 文件夹内的 `.diag.json` 文件中。基础模板示例如下：
|
||||
|
||||
::: code-group
|
||||
```json [dialogue/example.diag.json]
|
||||
{
|
||||
"format_version": "1.17",
|
||||
"minecraft:npc_dialogue": {
|
||||
"scenes": [
|
||||
{
|
||||
"scene_tag": "example",
|
||||
"npc_name": "Steve",
|
||||
"text": "你好"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
每个场景包含以下可配置参数：
|
||||
|
||||
#### scene_tag
|
||||
|
||||
场景唯一标识符，用于指定具体场景。
|
||||
|
||||
#### npc_name
|
||||
|
||||
NPC 显示名称。若省略，则使用 NPC 实体名称（默认为`§eNPC`）。
|
||||
|
||||
#### text
|
||||
|
||||
显示在对话框中的文本（可选）。
|
||||
|
||||
#### on_open_commands
|
||||
|
||||
打开对话框时执行的命令列表（可选）。
|
||||
|
||||
::: code-group
|
||||
```json
|
||||
"on_open_commands": [
|
||||
"/say 你好"
|
||||
]
|
||||
```
|
||||
:::
|
||||
|
||||
#### on_close_commands
|
||||
|
||||
关闭对话框时执行的命令列表（可选）。
|
||||
|
||||
::: code-group
|
||||
```json
|
||||
"on_close_commands": [
|
||||
"/say 再见"
|
||||
]
|
||||
```
|
||||
:::
|
||||
|
||||
#### buttons
|
||||
|
||||
对话框中显示的按钮配置（可选）。
|
||||
|
||||
::: code-group
|
||||
```json
|
||||
"buttons": [
|
||||
{
|
||||
"name": "按钮一",
|
||||
"commands": [
|
||||
"/say 按钮一被点击了！"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "按钮二",
|
||||
"commands": [
|
||||
"/say 按钮二被点击了！",
|
||||
"/say 第二段命令示例"
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
:::
|
||||
|
||||
## 玩家选择器
|
||||
|
||||
在 `on_open_commands`、`on_close_commands` 和各按钮的 `commands` 中可使用本地选择器 `@p`，但会以 NPC 实体为中心选择。特殊选择器 `@initiator` 可始终指向触发对话框的玩家。
|
||||
|
||||
::: code-group
|
||||
```json
|
||||
"buttons": [
|
||||
{
|
||||
"name": "获得漂浮效果",
|
||||
"commands": [
|
||||
"/effect @initiator levitation"
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
:::
|
||||
|
||||
注意：`@initiator` 专用于 NPC 对话框，不可在其他场景使用。
|
||||
|
||||
## 文本本地化
|
||||
|
||||
可通过翻译键实现多语言支持：
|
||||
|
||||
::: code-group
|
||||
```json
|
||||
"npc_name": {
|
||||
"rawtext": [
|
||||
{
|
||||
"translate": "entity.endermite.name"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
:::
|
||||
需在资源包语言文件中定义对应翻译键，例如 `entity.endermite.name` 对应中文为"末影螨"。
|
||||
|
||||
## 打开对话框
|
||||
|
||||
使用 `/dialogue` 命令开启对话框：
|
||||
```
|
||||
/dialogue open <npc: 目标> <player: 目标> [场景名称:string]
|
||||
```
|
||||
- `<npc: 目标>`：需携带 `minecraft:npc` 组件的实体（如原版 NPC）
|
||||
- `<player: 目标>`：目标玩家
|
||||
- `[场景名称:string]`：指定 `scene_tag`（若省略则显示上一个场景）
|
||||
|
||||
示例命令：
|
||||
```
|
||||
/dialogue open @e[type=npc,c=1] @p example
|
||||
```
|
||||
|
||||
## 切换对话框
|
||||
|
||||
使用以下语法变更 NPC 默认对话框：
|
||||
```
|
||||
/dialogue change <npc: 目标> <场景名称:string> [player: 目标]
|
||||
```
|
||||
- `<场景名称:string>`：指定新场景的 `scene_tag`
|
||||
- `[player: 目标]`：指定生效玩家（若省略则影响所有人）
|
||||
|
||||
示例命令：
|
||||
```
|
||||
/dialogue change @e[type=npc,c=1] example @r
|
||||
```
|
||||
|
||||
## 完整范例
|
||||
|
||||
本节演示创建具有传送功能的道具和对话系统（完整源码可参见[GitHub](https://github.com/Llama-Studios/dialog-demo)）。
|
||||
|
||||
### 创建 NPC 实体
|
||||
|
||||
即使隐藏 NPC，也需要通过常加载区域保持存在：
|
||||
|
||||
::: code-group
|
||||
```mcfunction [functions/setup.mcfunction]
|
||||
tickingarea add 0 1 0 0 2 0
|
||||
summon npc "§r" 0 1 0
|
||||
```
|
||||
:::
|
||||
|
||||
:::tip
|
||||
可通过玩家实体触发对话框：
|
||||
1. 为玩家添加 `minecraft:npc` 组件
|
||||
2. 映射行为包对话框场景
|
||||
3. 执行以下命令：
|
||||
```
|
||||
/dialogue open @s @s <scene_tag>
|
||||
```
|
||||
#### 优劣分析
|
||||
`+` 无需维护隐藏 NPC<br/>
|
||||
`+` 无需管理常加载区域<br/>
|
||||
`-` 非正常使用可能导致稳定性问题<br/>
|
||||
`-` 其他玩家点击该玩家时会显示对话框<br/>
|
||||
|
||||
可通过添加交互组件避免问题：
|
||||
::: code-group
|
||||
```json
|
||||
"minecraft:interact": {
|
||||
"interactions": [
|
||||
{
|
||||
"on_interact": {
|
||||
"filters": {
|
||||
"all_of": [
|
||||
{
|
||||
"test": "is_family",
|
||||
"subject": "other",
|
||||
"value": "player"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
:::
|
||||
:::
|
||||
|
||||
### 对话文件配置
|
||||
|
||||
::: code-group
|
||||
```json [dialogue/example.diag.json]
|
||||
{
|
||||
"format_version":"1.17",
|
||||
"minecraft:npc_dialogue":{
|
||||
"scenes":[
|
||||
{
|
||||
"scene_tag":"main_teleport_menu",
|
||||
"npc_name":"传送菜单",
|
||||
"text":"选择传送目的地",
|
||||
"buttons":[
|
||||
{
|
||||
"name":"区域传送",
|
||||
"commands":[
|
||||
"/dialogue open @e[type=npc,c=1] @initiator districts_teleport_menu"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name":"个人基地",
|
||||
"commands":[
|
||||
"/tp @initiator -20 4 -20"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name":"世界出生点",
|
||||
"commands":[
|
||||
"/tp @initiator 0 4 0"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"scene_tag":"districts_teleport_menu",
|
||||
"npc_name":"区域传送",
|
||||
"text":"请选择目标区域",
|
||||
"buttons":[
|
||||
{
|
||||
"name":"< 返回",
|
||||
"commands":[
|
||||
"/dialogue open @e[type=npc,c=1] @initiator main_teleport_menu"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name":"商业区",
|
||||
"commands":[
|
||||
"/tp @initiator 20 4 20"
|
||||
]
|
||||
},
|
||||
{
|
||||
"name":"娱乐区",
|
||||
"commands":[
|
||||
"/tp @initiator 20 4 -20"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 创建传送物品
|
||||
|
||||
::: code-group
|
||||
```json [items/teleport_menu.json]
|
||||
{
|
||||
"format_version": "1.16.100",
|
||||
"minecraft:item": {
|
||||
"description": {
|
||||
"identifier": "dialog:teleport_menu",
|
||||
"category": "物品"
|
||||
},
|
||||
"components": {
|
||||
"minecraft:on_use": {
|
||||
"on_use": {
|
||||
"event": "open_menu",
|
||||
"target": "self"
|
||||
}
|
||||
},
|
||||
"minecraft:foil": true,
|
||||
"minecraft:icon": {
|
||||
"texture": "ender_pearl"
|
||||
},
|
||||
"minecraft:display_name": {
|
||||
"value": "传送菜单"
|
||||
}
|
||||
},
|
||||
"events": {
|
||||
"open_menu": {
|
||||
"run_command": {
|
||||
"command": [
|
||||
"dialogue open @e[type=npc,c=1] @s main_teleport_menu"
|
||||
],
|
||||
"target": "player"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 测试步骤
|
||||
1. 在超平坦世界启用实验性玩法
|
||||
2. 执行 `/function setup` 创建 NPC
|
||||
3. 获取道具：`/give @s dialog:teleport_menu`
|
||||
4. 切换生存模式使用道具
|
||||
|
||||
## 版权声明
|
||||
|
||||
本教程改编自 [Minecraft 创作者文档](https://docs.microsoft.com/en-us/minecraft/creator/documents/npcdialogue)。
|
||||
310
docs/wiki/3-实体/1-基础/render-controllers.md
Normal file
310
docs/wiki/3-实体/1-基础/render-controllers.md
Normal file
@@ -0,0 +1,310 @@
|
||||
---
|
||||
title: 渲染控制器
|
||||
category: 常规
|
||||
tags:
|
||||
- beginner
|
||||
mentions:
|
||||
- SirLich
|
||||
- MedicalJewel105
|
||||
- Overload252
|
||||
- ChibiMango
|
||||
---
|
||||
|
||||
# 渲染控制器
|
||||
|
||||
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
|
||||
|
||||
渲染控制器是资源包中常被误解的部分。但您无需畏惧！您可以将渲染控制器视为逻辑包，它们接收来自资源包实体文件中的短名称定义，并决定这些资源在游戏中如何组合/分层/渲染。
|
||||
|
||||
## 定义短名称
|
||||
|
||||
渲染控制器基于资源包实体文件中的短名称定义运作。短名称是我们在资源包实体文件中定义的本地标识符，可供渲染控制器（及其他地方）调用。我们可以在实体中定义`geometry`（几何体）、`materials`（材质）和`textures`（纹理）等变量。
|
||||
|
||||
让我们看看蜘蛛资源包实体文件的简化版本：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/spider.json]
|
||||
{
|
||||
"format_version": "1.8.0",
|
||||
"minecraft:client_entity": {
|
||||
"description": {
|
||||
"identifier": "minecraft:cave_spider",
|
||||
"materials": {
|
||||
"default": "spider",
|
||||
"invisible": "spider_invisible"
|
||||
},
|
||||
"textures": {
|
||||
"default": "textures/entity/spider/cave_spider"
|
||||
},
|
||||
"geometry": {
|
||||
"default": "geometry.spider.v1.8"
|
||||
},
|
||||
"render_controllers": ["controller.render.spider"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
此示例中创建了四个短名称定义：
|
||||
- `default`（材质数组）
|
||||
- `invisible`（材质数组）
|
||||
- `default`（纹理数组）
|
||||
- `default`（几何体数组）
|
||||
|
||||
您可以在每个数组中定义多个短名称（如上方的材质示例）。将短名称定义视为_导入_所需资源的操作。在此阶段，您在定义实体要使用的纹理、几何体和材质。在渲染控制器阶段不会导入新内容，而是使用已导入的资源来构建最终渲染的实体。
|
||||
|
||||
## 简单渲染控制器
|
||||
|
||||
一个基础渲染控制器示例如下：
|
||||
|
||||
::: code-group
|
||||
```json [RP/render_controllers/cow.render.json]
|
||||
{
|
||||
"format_version": "1.8.0",
|
||||
"render_controllers": {
|
||||
"controller.render.cow": {
|
||||
"geometry": "Geometry.default",
|
||||
"materials": [
|
||||
{
|
||||
"*": "Material.default"
|
||||
}
|
||||
],
|
||||
"textures": ["Texture.default"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
该控制器从实体文件获取短名称定义并进行_渲染_。例如`"textures": [ "Texture.default"]`表达："采用default纹理并应用于实体"。渲染控制器本身并不知晓default纹理的具体内容，只是执行应用指令。
|
||||
|
||||
## 复用渲染控制器
|
||||
|
||||
由于渲染控制器基于短名称工作，您可以在所有实体中复用同一个渲染控制器。对于只含单一材质、单一纹理和单一几何体的简单实体，无需创建自定义渲染控制器。
|
||||
|
||||
例如上方示例的控制器用于`minecraft:cow`实体。若要在自定义包中使用此控制器，只需在实体文件中声明：`"render_controllers": [ "controller.render.cow" ]`。
|
||||
|
||||
:::warning 注意！
|
||||
渲染控制器基于短名称工作。若使用牛的渲染控制器，必须提供其所需的短名称：
|
||||
- `default`几何体
|
||||
- `default`纹理
|
||||
- `default`材质
|
||||
:::
|
||||
|
||||
## 创建自定义渲染控制器
|
||||
|
||||
当我们需要更精细控制实体渲染时（如分层纹理、多重几何体、不同骨骼应用不同材质），可通过复制原版渲染控制器到`render_controllers`文件夹进行定制化修改。
|
||||
|
||||
## 纹理分层
|
||||
|
||||
通过纹理分层技术可为自定实体创建叠加纹理。基础思路是通过多个纹理的透明像素区域实现叠加显示。
|
||||
|
||||
假设一个**画框**实体：框架固定但画面可变。虽然可以复制10个框架纹理并制作10幅画作，但修改框架时需要改动所有文件。采用分层纹理方案时，首先放置框架纹理，再叠加画作纹理，即可实现框架的集中管理。
|
||||
|
||||
### 通过渲染控制器实现
|
||||
|
||||
若对渲染控制器不熟悉，建议参考原版案例。例如含有多个纹理的`horse`实体具有典型参考价值。
|
||||
|
||||
#### 渲染控制器
|
||||
|
||||
::: code-group
|
||||
```json [RP/render_controllers/controller.render.texture_layering.json]
|
||||
{
|
||||
"format_version": "1.10.0",
|
||||
"render_controllers": {
|
||||
"controller.render.texture_layering": {
|
||||
"geometry": "Geometry.default",
|
||||
"materials": [
|
||||
{
|
||||
"*": "Material.default"
|
||||
}
|
||||
],
|
||||
"textures": [
|
||||
// 你可以添加任意数量的图层，按从上到下的顺序叠加
|
||||
"Texture.bottom_layer",
|
||||
"Texture.top_layer"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
#### 实体配置
|
||||
|
||||
需要定义所有纹理并使用`villager_v2_masked`材质：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/my_entity.json]
|
||||
"materials": {
|
||||
"default": "villager_v2_masked"
|
||||
},
|
||||
"textures": {
|
||||
"top_layer": "textures/top",
|
||||
"bottom_layer": "textures/bottom"
|
||||
// 在此添加更多纹理短名称定义
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 动态变体分层
|
||||
|
||||
通过动态索引实现纹理切换能创造更灵活的效果：
|
||||
|
||||
#### 实体配置
|
||||
|
||||
定义多个顶部纹理以供索引：
|
||||
|
||||
::: code-group
|
||||
```json [RP/entity/my_entity.json#description]
|
||||
"textures": {
|
||||
"top_1": "textures/top_1",
|
||||
"top_2": "textures/top_2",
|
||||
"top_3": "textures/top_3",
|
||||
"bottom_layer": "textures/bottom"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
#### 渲染控制器
|
||||
|
||||
::: code-group
|
||||
```json [RP/render_controllers/controller.render.wool_only]
|
||||
{
|
||||
"format_version": "1.10.0",
|
||||
"render_controllers": {
|
||||
"controller.render.wool_only": {
|
||||
"arrays": {
|
||||
"textures": {
|
||||
"Array.top": [
|
||||
"Texture.top_1",
|
||||
"Texture.top_2",
|
||||
"Texture.top_3"
|
||||
]
|
||||
}
|
||||
},
|
||||
"geometry": "Geometry.default",
|
||||
"materials": [
|
||||
{
|
||||
"*": "Material.default"
|
||||
}
|
||||
],
|
||||
"textures": [
|
||||
"Texture.bottom", // 静态底层纹理
|
||||
"Array.top[q.variant]" // 根据实体变体选择顶部纹理
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
通过数组和`q.variant`查询，可根据实体variant值动态选择顶部纹理。
|
||||
|
||||
#### 设置变体值
|
||||
|
||||
要使分层显示生效，需在实体中设置variant组件：
|
||||
|
||||
::: code-group
|
||||
```json [BP/entities/my_entity.json#components]
|
||||
"minecraft:variant": {
|
||||
"value": 0
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
注意组件参数采用零索引制，`0`对应第一个纹理，`1`和`2`对应后续纹理。
|
||||
|
||||
#### 动态更换纹理
|
||||
|
||||
如需在游戏中动态更换纹理，只需修改`variant`值。可通过组件组和事件系统实现此功能。
|
||||
|
||||
#### 动态分层进阶
|
||||
|
||||
通过添加更多纹理数组和使用虚拟组件（dummy components）作为索引，可实现更复杂的动态分层效果。关于虚拟组件的详细信息请参阅[此文档](/entities/dummy-components)。
|
||||
|
||||
### 动态几何体切换
|
||||
|
||||
动态切换几何体的原理与纹理类似：
|
||||
|
||||
以下示例展示如何根据variant值切换不同几何体。注意几何体不可分层叠加，因此不需要基础层定义，但仍需使用`villager_v2_masked`材质。
|
||||
|
||||
::: code-group
|
||||
```json [RP/render_controllers/controller.render.player.third_person.json]
|
||||
{
|
||||
"format_version": "1.8.0",
|
||||
"render_controllers": {
|
||||
"controller.render.player.third_person": {
|
||||
"materials": [
|
||||
{
|
||||
"*": "Material.default"
|
||||
}
|
||||
],
|
||||
"textures": [
|
||||
"Texture.bottom",
|
||||
"Array.top[q.variant]"
|
||||
],
|
||||
"arrays": {
|
||||
"geometries": {
|
||||
"Array.geo": [
|
||||
"Geometry.default",
|
||||
"Geometry.custom_1",
|
||||
"Geometry.custom_2"
|
||||
]
|
||||
},
|
||||
"textures": {
|
||||
"Array.top": [
|
||||
"Texture.bottom",
|
||||
"Texture.top_1",
|
||||
"Texture.top_2"
|
||||
]
|
||||
}
|
||||
},
|
||||
"geometry": "Array.geo[q.variant]"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
#### 实体配置
|
||||
|
||||
确保在实体文件中包含对应几何体变体：
|
||||
|
||||
::: code-group
|
||||
```json
|
||||
"geometry": {
|
||||
"default": "geometry.entity.default",
|
||||
"custom_1": "geometry.entity.custom_1",
|
||||
"custom_2": "geometry.entity.custom_2"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
## 常见错误
|
||||
|
||||
在渲染控制器中：
|
||||
- 可引用多个纹理但只能引用一个几何体（数组形式亦适用）
|
||||
|
||||
::: code-group
|
||||
```json
|
||||
"arrays": {
|
||||
"textures": {
|
||||
"array.skin": [],
|
||||
"array.dress": []
|
||||
},
|
||||
"geometries": {
|
||||
"array.geo": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
"textures": [
|
||||
"array.skin[q.variant]",
|
||||
"array.dress[q.skin_id]"
|
||||
],
|
||||
"geometry": "array.geo[q.mark_variant]"
|
||||
```
|
||||
:::
|
||||
159
docs/wiki/3-实体/1-基础/spawn-rules.md
Normal file
159
docs/wiki/3-实体/1-基础/spawn-rules.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: 实体生成规则
|
||||
category: 常规
|
||||
mentions:
|
||||
- SirLich
|
||||
- solvedDev
|
||||
- MedicalJewel105
|
||||
- aexer0e
|
||||
- Ciosciaa
|
||||
- FrankyRay
|
||||
- Luthorius
|
||||
- TheItsNameless
|
||||
- SmokeyStack
|
||||
---
|
||||
|
||||
# 实体生成规则
|
||||
|
||||
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
|
||||
|
||||
生成规则定义了实体如何自然生成到世界中。当您希望自定义实体像原版实体一样自然生成时，应该使用生成规则。通过不同的组件可以定义实体生成的时间、地点和方式。
|
||||
|
||||
通常情况下，可以让您的自定义实体采用与原版实体类似的生成方式。例如：像牛一样群生成、像原版僵尸一样仅在夜间生成，或是像鱼类只在水下生成。
|
||||
|
||||
## 生成规则示例
|
||||
|
||||
以下是一个包含字段说明的生成规则示例：
|
||||
|
||||
::: code-group
|
||||
```json [BP/spawn_rules/zombie.json]
|
||||
{
|
||||
"format_version": "1.8.0",
|
||||
"minecraft:spawn_rules": {
|
||||
"description": {
|
||||
"identifier": "minecraft:zombie",
|
||||
"population_control": "monster"
|
||||
},
|
||||
"conditions": [
|
||||
{
|
||||
"minecraft:spawns_on_surface": {},
|
||||
"minecraft:spawns_underground": {},
|
||||
"minecraft:brightness_filter": {
|
||||
"min": 0,
|
||||
"max": 7,
|
||||
"adjust_for_weather": true
|
||||
},
|
||||
"minecraft:difficulty_filter": {
|
||||
"min": "easy",
|
||||
"max": "hard"
|
||||
},
|
||||
"minecraft:weight": {
|
||||
"default": 100
|
||||
},
|
||||
"minecraft:herd": {
|
||||
"min_size": 2,
|
||||
"max_size": 4
|
||||
},
|
||||
"minecraft:permute_type": [
|
||||
{
|
||||
"weight": 95
|
||||
},
|
||||
{
|
||||
"weight": 5,
|
||||
"entity_type": "minecraft:zombie_villager"
|
||||
}
|
||||
],
|
||||
"minecraft:biome_filter": {
|
||||
"test": "has_biome_tag",
|
||||
"operator": "==",
|
||||
"value": "monster"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
- `description`→`identifier`: 要生成的实体
|
||||
- `population_control`: 控制生成与消失的数量。可选值：`animal`（动物）、`underwater_animal`（水生动物）、`monster`（怪物）、`ambient`（环境生物）
|
||||
- `conditions`: 必须满足的条件列表，生成尝试才会成功
|
||||
- `minecraft:spawns_on_surface`（地表生成）、`minecraft:spawns_underground`（地下生成）和`minecraft:spawns_underwater`（水下生成）控制实体生成的高度范围
|
||||
- `minecraft:brightness_filter`（亮度过滤）取值范围 0-15，控制生成所需光照条件。`adjust_for_weather`选项用于雨天/雷暴天气下是否自动降低有效光照值
|
||||
- `minecraft:difficulty_filter`（难度过滤）设置启用生成的游戏难度范围
|
||||
- `minecraft:herd`（群体生成）设置基于同个生成规则一起生成的实体数量
|
||||
- `minecraft:permute_type`（类型置换）通过`weight`权重和`entity_type`实体类型设置生成实体变异的概率
|
||||
- `minecraft:biome_filter`（生物群系过滤）测试特定生物群系标签。具体过滤器语法和生物群系标签列表请参考官方文档，或查看原版示例资源包
|
||||
|
||||
## 全部已知组件
|
||||
|
||||
以下是所有已知组件列表（随着我们对使用方法的理解加深，将持续补充说明文档）：
|
||||
|
||||
```
|
||||
minecraft:weight
|
||||
minecraft:density_limit
|
||||
minecraft:spawns_on_block_filter
|
||||
minecraft:spawns_on_block_prevented_filter
|
||||
minecraft:spawns_above_block_filter
|
||||
minecraft:herd
|
||||
minecraft:permute_type
|
||||
minecraft:brightness_filter
|
||||
minecraft:height_filter
|
||||
minecraft:spawns_on_surface
|
||||
minecraft:spawns_underground
|
||||
minecraft:spawns_underwater
|
||||
minecraft:disallow_spawns_in_bubble
|
||||
minecraft:spawns_lava
|
||||
minecraft:biome_filter
|
||||
minecraft:difficulty_filter
|
||||
minecraft:distance_filter
|
||||
minecraft:is_experimental
|
||||
minecraft:world_age_filter
|
||||
minecraft:delay_filter
|
||||
minecraft:mob_event_filter
|
||||
minecraft:is_persistent
|
||||
minecraft:player_in_village_filter
|
||||
```
|
||||
|
||||
## 组件文档
|
||||
|
||||
### minecraft:herd
|
||||
|
||||
::: code-group
|
||||
```json
|
||||
"minecraft:herd": {
|
||||
"min_size": 1,
|
||||
"max_size": 2,
|
||||
"event":"minecraft:entity_born",
|
||||
"event_skip_count": 1
|
||||
},
|
||||
```
|
||||
:::
|
||||
|
||||
- `minecraft:herd`可通过此配置使第二个生成的实体（在此场景中）携带`minecraft:entity_born`事件（表现为幼体）。`event_skip_count`: 2`表示前两个生成的实体不会触发事件，之后生成的都会携带该事件。该功能适用于任意事件类型
|
||||
|
||||
### minecraft:spawns_above_block_filter
|
||||
|
||||
::: code-group
|
||||
```json
|
||||
"minecraft:spawns_above_block_filter": {
|
||||
"blocks": "minecraft:stone",
|
||||
"distance": 10
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
- `minecraft:spawns_above_block_filter`（上方方块过滤）会检测垂直方向设定距离内的方块，当条件满足时允许实体生成
|
||||
|
||||
### minecraft:spawns_on_block_prevented_filter
|
||||
|
||||
::: code-group
|
||||
```json
|
||||
"minecraft:spawns_on_block_prevented_filter": [
|
||||
"minecraft:nether_wart_block",
|
||||
"minecraft:shroomlight"
|
||||
]
|
||||
```
|
||||
:::
|
||||
|
||||
- `minecraft:spawns_on_block_prevented_filter`（禁止生成方块过滤）与上方组件功能相反。该数组包含实体永远无法生成于其上的方块标识符
|
||||
158
docs/wiki/3-实体/1-基础/troubleshooting-entities.md
Normal file
158
docs/wiki/3-实体/1-基础/troubleshooting-entities.md
Normal file
@@ -0,0 +1,158 @@
|
||||
---
|
||||
title: 实体问题排查指南
|
||||
category: 常规
|
||||
nav_order: 3
|
||||
tags:
|
||||
- help
|
||||
mentions:
|
||||
- SirLich
|
||||
- BlueFrog130
|
||||
- SmokeyStack
|
||||
- MedicalJewel105
|
||||
- aexer0e
|
||||
- ChibiMango
|
||||
- RonarsCorruption
|
||||
---
|
||||
|
||||
# 实体问题排查指南
|
||||
|
||||
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
|
||||
|
||||
:::tip
|
||||
本页面包含关于_实体_的疑难解答信息。在继续阅读前，请务必先查阅[全局问题排查指南](/guide/troubleshooting)。
|
||||
:::
|
||||
|
||||
:::warning
|
||||
请始终记得检查内容日志！
|
||||
:::
|
||||
|
||||
## 0.0.0 - 确认问题存在
|
||||
|
||||
承认吧，某个地方肯定出错了。_任何_水平的开发者在_任何_阶段都可能出现这些疏漏，所以不要觉得被冒犯而想着"我当然会注意这些！"，然后跳过必要的检查步骤！
|
||||
|
||||
<BButton color="blue" link="#_1-0-0-are-both-packs-active">继续</BButton>
|
||||
|
||||
|
||||
## 1.0.0 - 确保两个包都已启用
|
||||
|
||||
确认资源包和行为包在世界中都已激活（一个绝佳的防错方法是在两个包的manifest.json文件中互相设置依赖，这样添加或移除其中一个包时会自动同步处理）
|
||||
|
||||
<BButton color="blue" link="#_2-0-0-determine-whether-the-issue-is-in-the-rp-or-the-bp">继续</BButton>
|
||||
|
||||
## 2.0.0 - 确定问题出现在资源包还是行为包
|
||||
|
||||
通过观察实体生成蛋在创造模式物品栏中的显示状态，可以有效定位问题范围。即使您不打算为实体添加生成蛋，请暂时按照以下步骤添加以便定位问题：
|
||||
|
||||
### 在资源包中
|
||||
|
||||
确保.entity文件包含自定义spawn_egg配置：
|
||||
|
||||
::: code-group
|
||||
```json [RP]
|
||||
"spawn_egg":{
|
||||
"base_color": "#FF0000",
|
||||
"overlay_color": "#FFFF00"
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
（建议选择除"#000000"以外的配色以方便排查）
|
||||
|
||||
### 在行为包中
|
||||
|
||||
确保description对象中开启`is_spawnable`和`is_summonable`，并将`is_experimental`设为false：
|
||||
|
||||
::: code-group
|
||||
```json [BP]
|
||||
"description":{
|
||||
"identifier": "wiki:example_entity",
|
||||
"is_spawnable": true,
|
||||
"is_summonable": true,
|
||||
"is_experimental": false
|
||||
}
|
||||
```
|
||||
:::
|
||||
|
||||
### 现象分析
|
||||
|
||||
完全看不到生成蛋：<BButton color="blue" link="#_3-1-0-bp">前往排查</BButton>
|
||||
|
||||
能看到生成蛋但颜色全黑且无法生成实体：<BButton color="blue" link="#step-3-2-0-rp-entity">前往排查</BButton>
|
||||
|
||||
生成蛋显示正常颜色但仍旧无法生成实体：<BButton color="blue" link="#step-3-3-0-rp-resources-still-writing-because-this-is-going-to-be-extensive">前往排查</BButton>
|
||||
|
||||
## 3.0.0 - 定位具体问题
|
||||
|
||||
## 3.1.0 - 行为包问题
|
||||
|
||||
_即使已在行为文件中设置"is_spawnable": true，在创造模式物品栏中依然无法找到生成蛋_
|
||||
|
||||
这通常表示游戏未能正确识别实体行为文件。常见原因包括：
|
||||
|
||||
- Json语法错误
|
||||
- 文件夹命名错误
|
||||
|
||||
### 3.1.1 - 语法错误
|
||||
|
||||
单个语法错误会导致整个json文件失效。建议使用[JSON验证工具](https://jsonlint.com/)检查文件的语法完整性（注：虽然该网站会将//注释视为错误，但在Minecraft中实际允许使用注释）
|
||||
|
||||
### 3.1.2 - 文件夹误命名
|
||||
|
||||
请确认行为包中的实体文件夹命名为"entities"（资源包对应的是"entity"，这个不一致设定确实容易引起困惑）
|
||||
|
||||
## 步骤3.2.0 - 资源包.entity文件问题
|
||||
|
||||
_能在创造模式物品栏中看到生成蛋，但显示为黑色且实体名异常（如"item.spawn_egg.entity.wiki:your_mob.name"），且无法正常生成实体_
|
||||
|
||||
此现象说明行为文件已生效，但资源包未能正确关联对应.entity文件。常见原因包括：
|
||||
|
||||
- .entity文件语法错误
|
||||
- 实体identifier不匹配
|
||||
- 资源引用路径错误
|
||||
- 资源包文件夹应命名为"entity"，行为包文件夹应命名为"entities"
|
||||
|
||||
### 步骤3.2.1 - 语法错误
|
||||
|
||||
再次推荐使用[JSON验证工具](https://jsonlint.com/)进行深度校验（注意注释标识的兼容性问题）
|
||||
|
||||
### 步骤3.2.2 - 标识符不匹配
|
||||
|
||||
需确保资源包.entity文件与行为包的identifier字段完全一致，包括命名空间（冒号前的部分，例如`minecraft:bat`中的`minecraft`）。特别注意：
|
||||
|
||||
- 除了冒号外不要使用特殊字符
|
||||
- 命名空间和ID避免以数字或大写字母开头（虽然现行版本允许，但历史版本曾存在兼容性问题）
|
||||
- 非官方实体切勿使用`minecraft`作为命名空间
|
||||
|
||||
### 步骤3.2.3 - 无效资源引用
|
||||
|
||||
检查.entity文件中各项资源引用路径是否正确指向有效文件
|
||||
|
||||
## 步骤3.3.0 - 资源包资源排查（进行中）
|
||||
|
||||
_生成蛋显示正常颜色但在生成/召唤时实体不可见或仅显示阴影_
|
||||
|
||||
这说明基本功能文件已正常加载，但存在次级资源配置问题。根据现象选择排查方向：
|
||||
|
||||
- 完全隐形无阴影 → 资源引用错误：<BButton link="#_3-3-1-invisible-no-shadow" color=blue >前往</BButton>
|
||||
- 隐形但显示阴影 → 几何体问题：<BButton link="#_3-3-2-invisible-shadow-exists" color=blue >前往</BButton>
|
||||
- 可见但贴图异常 → 材质问题：<BButton link="#_3-3-3-visible-weird-texture" color=blue >前往</BButton>
|
||||
- 可见但渲染异常 → 材质类型错误：<BButton link="#_3-3-4-visible-weird-visibility-stuff" color=blue >前往</BButton>
|
||||
|
||||
### 3.3.1 - 完全隐形无阴影
|
||||
|
||||
确认实体未设置立即消失逻辑（如instant_despawn），优先检查实体基础配置。
|
||||
|
||||
### 3.3.2 - 隐形但显示阴影
|
||||
|
||||
此类问题通常涉及模型或材质配置，排查重点：
|
||||
|
||||
1. 几何体文件：检查命名正确性、文件完整性和几何偏移量设置
|
||||
2. 材质匹配：例如透明材质与普通材质的兼容性
|
||||
3. 渲染控制器：验证控制器逻辑与参数设置
|
||||
|
||||
### 3.3.3 - 可见但贴图异常
|
||||
|
||||
（内容开发中）
|
||||
|
||||
### 3.3.4 - 可见但渲染异常
|
||||
（内容开发中）
|
||||
Reference in New Issue
Block a user