xiaokun/netease-modsdk-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

搬运一批Bedrock wiki内容，完善翻译

Browse Source
This commit is contained in:
boybook
2025-03-20 00:13:44 +08:00
parent ead7392a76
commit 4896c1a4f2
163 changed files with 33930 additions and 1464 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/wiki/1-Mod脚本开发/1-快速入门Mod开发.md
View File

@@ -100,8 +100,8 @@ class MyClientSystem(ClientSystem):
BOOM！就这么简单！
::: tip :bulb: 为什么需要这些System？
不太理解为什么需要这些System？来阅读进一步的解释吧！[为什么是System](./2-为什么是System.md)
:::details :bulb: 为什么需要这些System？
<!--@include: @/wiki/1-Mod脚本开发/为什么是System.md-->
:::
## 3. 运行你的Mod

44
docs/wiki/1-Mod脚本开发/2-为什么是System.md → docs/wiki/1-Mod脚本开发/为什么是System.md
View File

@@ -1,6 +1,8 @@
# 深入理解 System 的概念
---
hidden: true
---
## 🧩 为什么需要两个系统（System）？用餐厅来理解！
### 🧩 为什么需要两个系统（System）？用餐厅来理解！
想象一下游戏就像一家餐厅：
- **服务器系统** = 厨房（决定食物实际内容）
@@ -14,7 +16,7 @@ graph TB
end
```
## 👨‍🍳 服务器系统：游戏的"厨房"
### 👨‍🍳 服务器系统：游戏的"厨房"
- **职责**: 决定游戏中真正发生了什么
- **简单理解**:
@@ -23,7 +25,7 @@ graph TB
- 控制物品掉落
- 存储真实的游戏数据
## 👨‍💼 客户端系统：游戏的"前厅"
### 👨‍💼 客户端系统：游戏的"前厅"
- **职责**: 让玩家看到并互动
- **简单理解**:
@@ -32,7 +34,7 @@ graph TB
- 播放爆炸、火焰等特效
- 展示菜单和界面
## 📮 系统间如何交流：像传纸条一样
### 📮 系统间如何交流：像传纸条一样
当你在游戏中点击方块，发生了什么？
@@ -49,14 +51,14 @@ sequenceDiagram
前厅->>你: 播放挖矿动画和声音，显示物品
```
## ⚠️ 为什么不能混在一起？
### ⚠️ 为什么不能混在一起？
就像餐厅里顾客不能随便进厨房一样：
- ❌ 客户端不能直接修改游戏数据（否则会作弊）
- ❌ 服务器不负责播放声音和动画（它只关心真实数据）
## 🌟 简单例子：击打树木得钻石
### 🌟 简单例子：击打树木得钻石
### 简化理解版
1. **你点击树木**（客户端检测到）
@@ -65,7 +67,7 @@ sequenceDiagram
4. **服务器通知客户端**："请在玩家背包里显示一颗新钻石"
5. **客户端更新画面**：你看到钻石出现在背包里
## 🔑 记住这个简单规则
### 🔑 记住这个简单规则
想象游戏是一部电影：
- **服务器是导演**（决定故事情节）
@@ -73,7 +75,7 @@ sequenceDiagram
记住：**服务器决定发生什么，客户端决定如何展示**！
## 💡 初学者提示
### 💡 初学者提示
如果遇到问题，先问自己：
- "这个功能应该由谁负责？是真实游戏规则还是显示效果？"
@@ -82,9 +84,9 @@ sequenceDiagram
学会这种思考方式，你的Mod就能正确运行啦！
## :ribbon: 那么总结一下吧！
### :ribbon: 那么总结一下吧！
### 核心架构：客户端-服务器分离
#### 核心架构：客户端-服务器分离
```mermaid
graph TB
@@ -98,9 +100,9 @@ graph TB
end
```
### 双系统模型的必要性
#### 双系统模型的必要性
#### 服务器系统 (ServerSystem)
##### 服务器系统 (ServerSystem)
- **职责**: 维护游戏的"真实状态"
- **具体功能**:
- 处理游戏核心逻辑（如战斗计算、物品掉落）
@@ -108,7 +110,7 @@ graph TB
- 执行世界生成与物理规则
- **拥有数据的最终决定权**
#### 客户端系统 (ClientSystem)
##### 客户端系统 (ClientSystem)
- **职责**: 处理玩家的直接体验
- **具体功能**:
- 渲染游戏画面与UI界面
@@ -116,7 +118,7 @@ graph TB
- 播放音效与粒子效果
- 进行预测性渲染（平滑过渡）
### 系统间通信的关键：事件机制
#### 系统间通信的关键：事件机制
```mermaid
sequenceDiagram
@@ -131,12 +133,12 @@ sequenceDiagram
Client->>Player: 显示视觉反馈
```
#### 事件驱动设计的优势
##### 事件驱动设计的优势
- **松耦合**: 系统间无需直接相互调用
- **可扩展**: 多个系统可响应同一事件
- **清晰职责**: 服务端决定结果，客户端呈现效果
#### 实例：击打方块流程
##### 实例：击打方块流程
1. **客户端**: 检测到玩家点击方块，发送`BlockUseEvent`
2. **服务端**:
- 接收到事件，判断方块是否可被破坏
@@ -145,20 +147,20 @@ sequenceDiagram
- 播放方块破坏动画和音效
- 显示掉落物
### 常见问题与最佳实践
#### 常见问题与最佳实践
#### 避免的错误模式
##### 避免的错误模式
- ❌ 在客户端直接修改游戏状态
- ❌ 在服务端处理UI渲染逻辑
- ❌ 遗漏事件监听导致功能不同步
#### 最佳实践
##### 最佳实践
- ✅ 服务端验证所有游戏逻辑（防作弊）
- ✅ 合理使用自定义事件进行系统间通信
- ✅ 保持客户端代码专注于视觉体验优化
- ✅ 在事件参数中携带足够的上下文信息
### 跨系统通信示例
#### 跨系统通信示例
```python
# 服务端发送自定义事件到客户端

44
docs/wiki/2-方块/1-基础/blocks-intro.md
View File

@@ -295,28 +295,22 @@ tile.wiki:compass_block.name=指南针方块
## 下一步学习
<div class="grid grid-cols-1 lg:grid-cols-2 xl:grid-cols-3 gap-5 m-0 p-0">
<Card
title="扩展功能"
imgsrc-light="assets/images/homepage/crafting_table_0.png"
link="/blocks/block-components">
学习各类可用[方块组件](/blocks/block-components)打造独特玩法。
<br><br>
使用[geometry（几何组件）](/blocks/block-components#geometry)为方块添加自定义模型！还可以通过[collision_box（碰撞箱）](/blocks/block-components#collision-box)和[selection_box（选择框）](/blocks/block-components#selection-box)配置物理交互区域。
</Card>
<Card
title="创建变体"
imgsrc-light="assets/images/homepage/scripting.png">
利用[方块状态](/blocks/block-states)和[permutations（状态切换）](/blocks/block-permutations)实现条件触发的组件功能。
<br><br>
例如为储液罐方块添加多级液面高度功能，并支持多种液体类型。
</Card>
<Card
title="复刻原版"
imgsrc-light="assets/images/homepage/diamond_ore_0.png"
link="/blocks/block-components">
在<b class="orange px-1 rounded-md">原版复刻</b>分类中查看多个完整实现案例。
<br><br>
从简单的[自定义玻璃方块](/blocks/custom-glass-blocks)开始，体验[material_instances（材质实例）](/blocks/block-components#material-instances)的应用！
</Card>
</div>
<MyFeatures :items="[
{
title: '扩展功能',
desc: '学习各类可用方块组件打造独特玩法。使用geometry（几何组件）为方块添加自定义模型！还可以通过collision_box（碰撞箱）和selection_box（选择框）配置物理交互区域。',
link: '/blocks/block-components',
image: 'assets/images/homepage/crafting_table_0.png'
},
{
title: '创建变体',
desc: '利用方块状态和permutations（状态切换）实现条件触发的组件功能。例如为储液罐方块添加多级液面高度功能，并支持多种液体类型。',
image: 'assets/images/homepage/scripting.png'
},
{
title: '复刻原版',
desc: '在原版复刻分类中查看多个完整实现案例。从简单的自定义玻璃方块开始，体验material_instances（材质实例）的应用！',
link: '/blocks/block-components',
image: 'assets/images/homepage/diamond_ore_0.png'
}
]" />

91
docs/wiki/3-实体/2-巧思案例/boat-entities.md
View File

@@ -1,9 +1,9 @@
---
title: Creating Boats
category: Tutorials
title: 创建船只
category: 教程
tags:
- recipe
- intermediate
- 配方
- 进阶
mentions:
- SirLich
- Joelant05
@@ -11,25 +11,29 @@ mentions:
- StealthyExpertX
- TheItsNameless
---
:::warning Requires Format Version 1.16.100 or Lower
The behavior format version now requires 1.16.100 or lower for the `minecraft:behavior.rise_to_liquid_level` and `minecraft:buoyant` methods to work.
If you find a new method that works in the newer format versions, you should consider helping to contribute by updating the wiki.
# 创建船只
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
:::warning 需要格式版本1.16.100或更低
当前行为格式版本要求1.16.100或更低版本才能使`minecraft:behavior.rise_to_liquid_level`和`minecraft:buoyant`功能生效。
如果您发现新格式版本中的替代实现方法，欢迎协助更新本Wiki内容。
:::
## Using Runtime Identifiers
## 使用运行时标识符
You can read more about runtime identifiers [here](/entities/runtime-identifier). Using runtime identifiers, you can implement most of the boat's hard-coded behaviors. However, your boat won't rotate with you, and it will always face North.
详细内容请参阅[运行时标识符指南](/entities/runtime-identifier)。使用运行时标识符可以实现船只的大部分硬编码行为，但会导致船只无法随玩家转向且始终面向北方。
## Using Components
## 利用组件系统实现
Currently, the best way to create a boat entity is by using components. 1.16 introduced new components that we can use to our advantage: `minecraft:behavior.rise_to_liquid_level` and `minecraft:buoyant`. Striders use the first one in vanilla to make them float on lava, but we can repurpose it for water as well.
目前最佳的船只创建方案是通过组件系统实现。1.16版本新增的两个组件可资利用：`minecraft:behavior.rise_to_liquid_level`与`minecraft:buoyant`。官方设计中前者用于岩浆怪的岩浆漂浮特性，我们可以将其移植到水面上使用。
## 1st method: minecraft:behavior.rise_to_liquid_level
## 第一种方法：minecraft:behavior.rise_to_liquid_level
<CodeHeader>BP/entities/bar</CodeHeader>
```json
::: code-group
```json [BP/entities/bar]
{
"minecraft:entity": {
"format_version": "1.14.0",
@@ -40,23 +44,23 @@ Currently, the best way to create a boat entity is by using components. 1.16 int
"is_experimental": false
},
"components": {
//This is the component that does the magic
// 这是实现效果的核心组件
"minecraft:behavior.rise_to_liquid_level": {
"priority": 0,
//This property can adjust how high your boat is above the water
// 控制船体相对于水面的基准高度
"liquid_y_offset": 0.5,
//Positive vertical displacement, in other words, how much the boat will move up
// 正垂直位移量，决定船体抬升幅度
"rise_delta": 0.05,
//Negative vertical displacement, in other words, how much the boat will move down
// 负垂直位移量，决定船体下沉幅度
"sink_delta": 0.05
//Use rise_delta and sink_delta to simulate waves/bouncing effect
// 通过升降参数可模拟波浪浮动效果
},
//Sets the boat speed in water
// 设置水上移动速率
"minecraft:underwater_movement": {
"value": 5
},
//This component is important, without it the boat will sink
// 关键组件，移除会导致船体沉没
"minecraft:navigation.walk": {
"can_sink": false
},
@@ -68,17 +72,17 @@ Currently, the best way to create a boat entity is by using components. 1.16 int
"position": [0, 0, 0]
}
},
//Add this component if you want your boat to be controlled with WASD
// 添加此组件实现WASD方向控制
"minecraft:input_ground_controlled": {},
"minecraft:health": {
"value": 10,
"max": 10
},
//Sets the boat speed on the ground (set this to zero if you don't want your boats to move on the ground)
// 设置地面移动速度（设置为0可禁用地表移动）
"minecraft:movement": {
"value": 3
},
//This is to prevent the boat from not stopping whenever a player exits, said the boat
// 防止玩家下船后无法停止移动
"minecraft:movement.basic": {},
"minecraft:collision_box": {
"width": 1,
@@ -89,12 +93,12 @@ Currently, the best way to create a boat entity is by using components. 1.16 int
}
}
```
:::
## 2nd method: minecraft:buoyant
## 第二种方法：minecraft:buoyant
<CodeHeader></CodeHeader>
```json
::: code-group
```json []
{
"minecraft:entity": {
"format_version": "1.14.0",
@@ -106,27 +110,27 @@ Currently, the best way to create a boat entity is by using components. 1.16 int
},
"components": {
"minecraft:buoyant": {
//Determines whether gravity should be taken into account (useful with waterfalls)
// 是否受重力影响（处理瀑布场景很有用）
"apply_gravity": true,
//Range: 0-1. This controls how high the boat is above the water
// 范围0-1，控制船体默认高度
"base_buoyancy": 1.0,
//A "wave" makes the entity bounce up and down. A big wave simply amplifies this effect. Note: setting simulate_waves to false won't make the effect go away completely.
// 「浪涌」模拟船体上下波动效果（false也不会完全消除效果）
"simulate_waves": true,
//How likely a "big" wave will hit this boat
// 产生「大浪」的概率
"big_wave_probability": 0.03,
//How strong the "big" wave will be
// 「大浪」强度系数
"big_wave_speed": 10.0,
//How strong will the boat be dragged down in case this component is removed
// 移除浮力后的下沉阻力
"drag_down_on_buoyancy_removed": 0,
//Blocks this entity can be buoyant in. Only actual liquids are allowed: lava and water
// 支持浮力的液态方块（仅限水和岩浆）
"liquid_blocks": ["water"]
},
//Sets the boat speed in water
// 设置水上移动速率
"minecraft:underwater_movement": {
"value": 5
},
//This component is important, without it the boat will sink
// 关键组件，移除会导致船体沉没
"minecraft:navigation.walk": {
"can_sink": false
},
@@ -138,17 +142,17 @@ Currently, the best way to create a boat entity is by using components. 1.16 int
"position": [0, 0, 0]
}
},
//Add this component if you want your boat to be controlled with WASD
// 添加此组件实现WASD方向控制
"minecraft:input_ground_controlled": {},
"minecraft:health": {
"value": 10,
"max": 10
},
//Sets the boat speed on the ground (set this to zero if you don't want your boats to move on the ground)
// 设置地面移动速度（设置为0可禁用地表移动）
"minecraft:movement": {
"value": 3
},
//This is to prevent the boat from not stopping whenever a player exits the boat
// 防止玩家下船后无法停止移动
"minecraft:movement.basic": {},
"minecraft:collision_box": {
"width": 1,
@@ -159,7 +163,8 @@ Currently, the best way to create a boat entity is by using components. 1.16 int
}
}
```
:::
## What method to use?
## 方法选择建议
Both methods are suitable but have their pros and cons. If you want to disable the bouncing effect, use the first method. If you want more control over it, use the second method. I use the second method for static objects, such as buoys, and the first method for movable entities, such as boats, emulating the vanilla behavior.
两种方式各有优劣。若需禁用波动效果建议采用第一种方式；若需要进行精细调控可选择第二种方法。开发实践中，第二种常用于浮标等静态物体，第一种则更适合船只等运动实体，能更好地还原原版特性。

305
docs/wiki/3-实体/2-巧思案例/detecting-other-entities.md
View File

@@ -1,8 +1,8 @@
---
title: Detecting Other Entities
category: Tutorials
title: 侦测其他实体
category: 教程
tags:
- intermediate
- 中级
mentions:
- ANightDazingZoroark
- SmokeyStack
@@ -12,210 +12,189 @@ mentions:
- TheItsNameless
---
You might have thought about making your entities fire an event when other entities are nearby. This article details the various known ways to do so.
# 侦测其他实体
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
当需要让实体在附近存在其他实体时触发事件，本文将详细介绍多种已知实现方式。
## minecraft:entity_sensor
This is probably the most basic way to detect other entities. The main issues is it only accepts one entry and testing if the entity is out of range can be very tricky. Because it's an entity component, you can just place into your entity behavior file and edit the Minecraft filters. Here's a demonstration:
这是最基础的侦测方式。主要限制是只能接收单一条目，且检测实体退出范围较困难。作为实体组件，可直接植入实体行为文件并配置Minecraft过滤器：
<CodeHeader>BP/entities/my_entity.json#components</CodeHeader>
```json
::: code-group
```json [BP/entities/my_entity.json#components]
"minecraft:entity_sensor": {
"sensor_range": 2.5, //this is for the radius in blocks it will detect other entities in
"relative_range": false, //if true, the sensor range is additive on top of the entity's hitbox size
"require_all": true, //if true, all nearby entities must pass the filter conditions for the event to send
"minimum_count": 1, //minimum amount of entities required for the event to fire. by default, it's 1
"maximum_count": 4, //maximum amount of entities required for the event to fire. by default it's -1, which means infinity
"event_filters": { //you can put any filter you want here, the one that's being used in this example just detects players
"sensor_range": 2.5, //检测半径（格子数）
"relative_range": false, //若为true，检测范围会叠加实体碰撞箱
"require_all": true, //若为true，所有邻近实体需通过过滤条件才会触发事件
"minimum_count": 1, //触发事件的最小实体数量（默认1）
"maximum_count": 4, //触发事件的最大实体数量（默认-1表示无限）
"event_filters": { //自定义过滤器（本例检测玩家）
"test": "is_family",
"subject": "other",
"value": "player"
},
"event": "event:on_player_detected" //the event that fires when all the conditions in event_filters are met
"event": "event:on_player_detected" //条件满足时触发的事件
}
```
:::
## `/execute`
## `/execute` 命令
Using the new `/execute` command that has been introduced since 1.19.50, you can execute commands as long as another entity is nearby.
使用1.19.50版本新增的`/execute`命令，可在附近存在实体时执行指令。以下示例使猪在检测到玩家时发出"oink oink"声（可自定义事件）：
This example you'll be following will make pigs say "oink oink" upon detecting players, though you can replace those with whatever you want. First of all, copy-paste these BP animations.
<CodeHeader>BP/animations/detection_animation.json</CodeHeader>
```json
::: code-group
```json [BP/animations/detection_animation.json]
{
"format_version": "1.10.0",
"animations": {
"animation.pig.find_player": {
"animation_length": 0.05,
"loop": true,
"timeline": {
"0": [
"/execute as @s if entity @e[type=player, r=4] run event entity @s wiki:player_detected"
]
}
"format_version": "1.10.0",
"animations": {
"animation.pig.find_player": {
"animation_length": 0.05,
"loop": true,
"timeline": {
"0": [
"/execute as @s if entity @e[type=player, r=4] run event entity @s wiki:player_detected"
]
}
},
"animation.pig.find_no_player": {
"animation_length": 0.05,
"loop": true,
"timeline": {
"0": [
"/execute as @s unless entity @e[type=player, r=4] run event entity @s wiki:no_player_detected"
]
}
}
}
}
```
:::
首个动画用于检测实体存在，第二个检测实体离开。可通过`/event`命令添加[虚拟组件](/entities/dummy-components)或更新[实体属性](https://learn.microsoft.com/zh-cn/minecraft/creator/documents/introductiontoentityproperties)。
::: code-group
```json [BP/animation_controllers/pig_animation_controllers.json]
{
"format_version": "1.10.0",
"animation_controllers": {
"controller.animation.pig_find_player": {
"initial_state": "default",
"states": {
"default": {
"animations": ["find_player"],
"transitions": [{
"detected": "q.is_sheared"
}]
},
"animation.pig.find_no_player": {
"animation_length": 0.05,
"loop": true,
"timeline": {
"0": [
"/execute as @s unless entity @e[type=player, r=4] run event entity @s wiki:no_player_detected"
]
}
"detected": {
"animations": ["find_no_player"],
"transitions": [{
"default": "!q.is_sheared"
}],
"on_entry": ["/say oink oink"]
}
}
}
}
}
```
:::
The first one is for detecting if the entity is present, and the other for detecting if the entity is not present. The events used in the `/event` part of the `/execute` commands can be used for adding a [dummy component](/entities/dummy-components) or updating an [actor property](https://learn.microsoft.com/en-us/minecraft/creator/documents/introductiontoentityproperties).
Next of all, copy paste this BP animation controller. This assumes that you set up the `/event` parts of the `/execute` commands to add or remove `minecraft:is_sheared`.
<CodeHeader>BP/animation_controllers/pig_animation_controllers.json</CodeHeader>
```json
{
"format_version": "1.10.0",
"animation_controllers": {
"controller.animation.pig_find_player": {
"initial_state": "default",
"states": {
"default": {
"animations": ["find_player"],
"transitions": [
{
"detected": "q.is_sheared"
}
]
},
"detected": {
"animations": ["find_no_player"],
"transitions": [
{
"default": "!q.is_sheared"
}
],
"on_entry": ["/say oink oink"]
}
}
}
}
}
```
Finally, copy-paste this snippet into the behavior file for the pig-like so. Make sure to insert this in `description`.
<CodeHeader>BP/entities/my_entity.json#description</CodeHeader>
```json
::: code-group
```json [BP/entities/my_entity.json#description]
"animations": {
"manage_find_player": "controller.animation.pig_find_player",
"find_player": "animation.pig.find_player",
"find_no_player": "animation.pig.find_no_player"
"manage_find_player": "controller.animation.pig_find_player",
"find_player": "animation.pig.find_player",
"find_no_player": "animation.pig.find_no_player"
},
"scripts": {
"animate": [
"manage_find_player"
]
"animate": ["manage_find_player"]
}
```
:::
## Molang, BP Animations & Animation Controllers
## Molang、动画与动画控制器
The `for_each` function and `q.get_nearby_entities` or `q.get_nearby_entities_except_self` can also be used for detecting other entities. They are more effective than using `minecraft:entity_sensor` because they are better at detecting if the entity you want to detect goes away than with `minecraft:entity_sensor`. The only downside is that they're experimental.
使用`for_each`函数配合`q.get_nearby_entities`或`q.get_nearby_entities_except_self`可更高效检测实体（实验性功能），能更好处理实体离开的情况。
Just like in the previous method we will make pigs say "oink oink" upon detecting players, though you can replace those with whatever you want. First of all, copy-paste this BP animation:
<CodeHeader>BP/animations/detection_animation.json</CodeHeader>
```json
::: code-group
```json [BP/animations/detection_animation.json]
{
"format_version": "1.10.0",
"animations": {
"animation.pig.find_player": {
"animation_length": 0.05,
"loop": true,
"timeline": {
"0": [
"v.x = 0.0; for_each(t.player, q.get_nearby_entities_except_self(16, 'minecraft:player'), { v.x = v.x + 1; }); return v.x > 0.0;"
]
}
}
}
"format_version": "1.10.0",
"animations": {
"animation.pig.find_player": {
"animation_length": 0.05,
"loop": true,
"timeline": {
"0": [
"v.x = 0.0; for_each(t.player, q.get_nearby_entities_except_self(16, 'minecraft:player'), { v.x = v.x + 1; }); return v.x > 0.0;"
]
}
}
}
}
```
:::
The first parameter that `q.get_nearby_entities_except_self` needs to work is the radius in blocks it will detect other entities in. The other is the identifier of the mob you want to make it detect.
若要检测具备特定Molang属性的实体：
Now that's good and all, but on the off chance, you want to make the pig detect players with some attribute that can be detected with Molang, use this.
<CodeHeader>BP/animations/detection_animation.json</CodeHeader>
```json
::: code-group
```json [BP/animations/detection_animation.json]
{
"format_version": "1.10.0",
"animations": {
"animation.pig.find_player": {
"animation_length": 0.05,
"loop": true,
"timeline": {
"0": [
"v.x = 0.0; for_each(t.player, q.get_nearby_entities_except_self(2, 'minecraft:player'), { v.x = v.x + (t.player -> q.is_sheared); }); return v.x > 0.0;"
]
}
}
}
"format_version": "1.10.0",
"animations": {
"animation.pig.find_player": {
"animation_length": 0.05,
"loop": true,
"timeline": {
"0": [
"v.x = 0.0; for_each(t.player, q.get_nearby_entities_except_self(2, 'minecraft:player'), { v.x = v.x + (t.player -> q.is_sheared); }); return v.x > 0.0;"
]
}
}
}
}
```
:::
Next of all, copy paste this BP animation controller:
<CodeHeader>BP/animation_controllers/pig_animation_controllers.json</CodeHeader>
```json
::: code-group
```json [BP/animation_controllers/pig_animation_controllers.json]
{
"format_version": "1.10.0",
"animation_controllers": {
"controller.animation.pig_find_player": {
"initial_state": "default",
"states": {
"default": {
"animations": ["find_player"],
"transitions": [
{
"detected": "v.x > 0"
}
]
},
"detected": {
"animations": ["find_player"],
"transitions": [
{
"default": "v.x <= 0"
}
],
"on_entry": ["/say oink oink"]
}
}
}
}
"format_version": "1.10.0",
"animation_controllers": {
"controller.animation.pig_find_player": {
"initial_state": "default",
"states": {
"default": {
"animations": ["find_player"],
"transitions": [{
"detected": "v.x > 0"
}]
},
"detected": {
"animations": ["find_player"],
"transitions": [{
"default": "v.x <= 0"
}],
"on_entry": ["/say oink oink"]
}
}
}
}
}
```
:::
Finally, copy-paste this snippet into the behavior file for the pig-like so. Make sure to insert this in `description`.
<CodeHeader>BP/entities/my_entity.json#description</CodeHeader>
```json
::: code-group
```json [BP/entities/my_entity.json#description]
"animations": {
"manage_find_player": "controller.animation.pig_find_player",
"find_player": "animation.pig.find_player"
"manage_find_player": "controller.animation.pig_find_player",
"find_player": "animation.pig.find_player"
},
"scripts": {
"animate": [
"manage_find_player"
]
"animate": ["manage_find_player"]
}
```
:::

124
docs/wiki/3-实体/2-巧思案例/disabling-team-damage.md
View File

@@ -1,8 +1,8 @@
---
title: Disabling Team-damage
category: Tutorials
title: 禁用团队伤害
category: 教程
tags:
- intermediate
- 中级
mentions:
- SirLich
- solvedDev
@@ -12,28 +12,32 @@ mentions:
- TCLynx
---
If you wish to disable team damage (so one cannot hurt their teammates), assign a tag with the team name to every teammate (I'm going to use `team1`, `team2`, `team3` and `team4` for this example).
WARNING: This will NOT work on realms, the reason for this is that on realms there is a bug where modified player.json files in the behavior packs do not work, and the gmae just ignores them (This may be fixed in the future but as of 1.20.15 it is not fixed. (This also applies to older version of minecraft as well.))
Now add this damage sensor component into your `player.json`s `"components": {}`. See comments for explanation.
# 禁用团队伤害
<CodeHeader>BP/entities/player.json#components</CodeHeader>
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
```json
若需禁用团队伤害（使玩家无法攻击队友），请为每位玩家分配带有队伍名称的标签（本教程将使用`team1`、`team2`、`team3`和`team4`作为示例）。
警告：该方法在领域服（Realms）中**不可用**，原因是领域服存在一个漏洞会导致行为包中修改后的player.json文件失效，游戏会直接忽略这些修改（该问题可能在后续版本中修复，但在1.20.15版本中尚未解决。此问题也影响更早的Minecraft版本）。
现在将以下伤害感应器组件添加至你的`player.json`文件的`"components": {}`部分。查看注释以获取详细说明。
::: code-group
```json [BP/entities/player.json#components]
"minecraft:damage_sensor":{
"triggers":[
{ //if you already have a damage sensor, simply copy this object into the "triggers" array
{ //若已有伤害感应器组件，只需将此对象复制到"triggers"数组中
"on_damage":{
"filters":{
"any_of":[
{
"all_of":[
{ "test":"has_tag", "value":"team1" }, //Does the player have this tag?
{ "test":"has_tag", "subject":"other", "value":"team1" } //If so, does the entity they're trying to hurt have this tag?
{ "test":"has_tag", "value":"team1" }, //该玩家是否拥有此标签？
{ "test":"has_tag", "subject":"other", "value":"team1" } //被攻击实体是否拥有此标签？
]
},
{
"all_of":[
{ "test":"has_tag", "value":"team2" }, //repeats for every team
"all_of":[ //以下为重复结构，为每个队伍添加相同配置
{ "test":"has_tag", "value":"team2" },
{ "test":"has_tag", "subject":"other", "value":"team2" }
]
},
@@ -58,30 +62,26 @@ Now add this damage sensor component into your `player.json`s `"components": {}`
]
}
},
"deals_damage":false //if any of these filters evaluate to true in the current attack interaction, the target will not be hurt.
"deals_damage":false //若任意过滤器条件满足，本次攻击将不会造成伤害
}
]
}
```
:::
### Projectiles
### 抛射物处理
Due to the primitive filters used by projectile entities, you have to use a completely different method to achieve this.
由于抛射物实体使用的原始滤镜系统，实现此功能需要完全不同的方法。该方案需要以下组件：
- 标签（Tags）
- 周期性检测（Ticking）
- 条件伤害（Hurt on Condition）
- 函数（Functions）
The process uses:
- Tags
- Ticking
- Hurt on Condition
- Functions
<CodeHeader>BP/entities/player.json#components</CodeHeader>
```json
//"components"
"minecraft:timer": { //This is for applying teams to a projectile to nearby
"time": [ //untagged projectiles, through an event.
::: code-group
```json [BP/entities/player.json#components]
//"components"部分
"minecraft:timer": { //用于通过事件给附近未标记的抛射物添加队伍标签
"time": [
0.0,
0.1
],
@@ -91,9 +91,9 @@ The process uses:
"target": "self"
}
},
"minecraft:hurt_on_condition": { //The projectile will be unable to directly deal
"damage_conditions": [ //damage, so instead we'll apply tags to the
{ //player, which will trigger this . . .
"minecraft:hurt_on_condition": { //使抛射物无法直接造成伤害
"damage_conditions": [ //改为通过标签系统触发伤害
{
"filters": {
"test": "has_tag",
"value": "damage"
@@ -103,9 +103,9 @@ The process uses:
}
]
},
"minecraft:damage_sensor": { //. . . which in turn, will trigger an event
"triggers": { //to remove this tag, so the damage only
"cause": "projectile", //happens once.
"minecraft:damage_sensor": { //触发事件来移除damage标签
"triggers": { //确保伤害只生效一次
"cause": "projectile",
"deals_damage": true,
"on_damage": {
"filters": {
@@ -117,15 +117,15 @@ The process uses:
}
}
//"events"
"wiki:projectile_team": { //The function here will apply tags depending on
"run_command": { //which team tags the player has.
//"events"部分
"wiki:projectile_team": { //根据玩家队伍标签应用对应的抛射物标签
"run_command": {
"command": [
"function wiki-apply_team"
]
}
},
"wiki:stop_damage": { //The event that simply removes the damage tag.
"wiki:stop_damage": { //移除damage标签的事件
"run_command": {
"command": [
"tag @s remove damage"
@@ -133,23 +133,13 @@ The process uses:
}
}
```
:::
<CodeHeader>BP/functions/wiki-apply_team.mcfunction</CodeHeader>
::: code-group
```
execute @s[tag=team1] ~ ~ ~ tag @e[rm=0,r=1,c=1,type=arrow,tag=] add team1
execute @s[tag=team2] ~ ~ ~ tag @e[rm=0,r=1,c=1,type=arrow,tag=] add team2
execute @s[tag=team3] ~ ~ ~ tag @e[rm=0,r=1,c=1,type=arrow,tag=] add team3
execute @s[tag=team4] ~ ~ ~ tag @e[rm=0,r=1,c=1,type=arrow,tag=] add team4
```
<CodeHeader>BP/entities/arrow.json</CodeHeader>
```json
//"components"
"on_hit": { //On_hit, trigger an event . . .
```json [BP/entities/arrow.json]
//"components"部分
"on_hit": { //击中时触发事件...
"definition_event": {
"affect_projectile": true,
"event_trigger": {
@@ -160,25 +150,35 @@ execute @s[tag=team4] ~ ~ ~ tag @e[rm=0,r=1,c=1,type=arrow,tag=] add team4
"remove_on_hit": {}
}
//"events"
"wiki:hit": { //. . . which executes a function, applying
"run_command": { //the damage tag to any players of a different team!
//"events"部分
"wiki:hit": { //...执行函数，为不同队伍玩家添加damage标签
"run_command": {
"command": [
"function wiki-apply_damage"
]
}
}
```
:::
<CodeHeader>BP/functions/wiki-apply_damage.mcfunction</CodeHeader>
::: code-group
```mcfunction [BP/functions/wiki-apply_team.mcfunction]
execute @s[tag=team1] ~ ~ ~ tag @e[rm=0,r=1,c=1,type=arrow,tag=] add team1
execute @s[tag=team2] ~ ~ ~ tag @e[rm=0,r=1,c=1,type=arrow,tag=] add team2
execute @s[tag=team3] ~ ~ ~ tag @e[rm=0,r=1,c=1,type=arrow,tag=] add team3
execute @s[tag=team4] ~ ~ ~ tag @e[rm=0,r=1,c=1,type=arrow,tag=] add team4
```
:::
::: code-group
```mcfunction [BP/functions/wiki-apply_damage.mcfunction]
execute @s[tag=team1] ~ ~ ~ tag @p[rm=0,r=1,tag=!team1] add damage
execute @s[tag=team2] ~ ~ ~ tag @p[rm=0,r=1,tag=!team2] add damage
execute @s[tag=team3] ~ ~ ~ tag @p[rm=0,r=1,tag=!team3] add damage
execute @s[tag=team4] ~ ~ ~ tag @p[rm=0,r=1,tag=!team4] add damage
```
:::
If you modify `arrow.json`, take into consideration the component groups.
> 注意：若修改`arrow.json`文件，请仔细考虑组件分组（component groups）的影响。

67
docs/wiki/3-实体/2-巧思案例/dummy-entities.md
View File

@@ -1,8 +1,8 @@
---
title: Dummy Entities
category: Tutorials
title: 虚拟实体
category: 教程
tags:
- beginner
- 初学者
mentions:
- SirLich
- Joelant05
@@ -10,26 +10,29 @@ mentions:
- aexer0e
---
Dummy entities are invisible entities which are used behind the scenes for game-play purposes. Dummy entities are a very useful tool, and this document will cover some of the ways they are utilized, as well as showing how to set up the resource side of things.
# 虚拟实体
## Using Dummies
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
This is a non-exhaustive list of how dummies can be used:
虚拟实体是游戏场景中不可见的幕后实用实体。本文将介绍这种多功能工具的使用场景，并展示如何配置资源文件。
- **For data storage**: by adding tags to the entity, we can use it as a "game manager", much like Armor Stands used to be used.
- **As a named entity:** by name-tagging a dummy, and then using `execute` to select for it, you can make command-blocks `/say` with a pretty display name.
- **As a location marker:** you can run `execute` commands located at a dummy to get relative coordinates at a location.
- **As a waypoint:** by making entities which are aggressive to your dummy, you can pathfind entities to any location by placing a dummy there.
## 核心用途
## Creating Dummies
以下是虚拟实体的部分应用场景：
### Behavior Entity
- **数据存储**：通过给实体添加标签，我们可以将其作为"游戏管理器"使用（类似过去盔甲架的用法）。
- **命名实体**：通过命名标签标识虚拟实体，配合`execute`指令选中目标，可以用命令块实现带精美显示名称的`/say`命令。
- **坐标标记**：通过`execute`指令跟踪虚拟实体位置，获取相对坐标系的基准点。
- **路径向导**：使敌对生物将虚拟实体设为目标，即可将实体路径引导至虚拟实体所在位置。
You can use whatever behaviors you like, but here is a good template. The important aspects are: no damage, and can't be pushed.
## 创建教程
<CodeHeader>BP/entities/dummy.json</CodeHeader>
### 行为配置
```json
这里提供一个标准模板（关键特性：免疫伤害且不可推动）。
::: code-group
```json [BP/entities/dummy.json]
{
"format_version": "1.16.0",
"minecraft:entity": {
@@ -40,11 +43,11 @@ You can use whatever behaviors you like, but here is a good template. The import
"is_experimental": false
},
"components": {
"minecraft:breathable": { //Optional, allows the entity to breath underwater
"minecraft:breathable": { // 可选，使实体能够在水中呼吸
"breathes_water": true
},
"minecraft:physics": {
"has_gravity": false, //Optional, allows the entity to not be affected by gravity or water
"has_gravity": false, // 可选，使实体不受重力和水流影响
"has_collision": false
},
"minecraft:custom_hit_test": {
@@ -74,13 +77,12 @@ You can use whatever behaviors you like, but here is a good template. The import
}
```
If you want to disable collision at all (so you can place a block at it's position), you can use arrow runtime identifier, however, there can be some side effects.
若要完全禁用碰撞（允许在其位置放置方块），可以使用弓箭runtime ID，但可能存在副作用。
### Resource Entity
### 资源配置
<CodeHeader>RP/entity/dummy.json</CodeHeader>
```json
::: code-group
```json [RP/entity/dummy.json]
{
"format_version": "1.10.0",
"minecraft:client_entity": {
@@ -100,12 +102,12 @@ If you want to disable collision at all (so you can place a block at it's positi
}
}
```
:::
### Geometry
### 模型配置
<CodeHeader>RP/models/entity/dummy.json</CodeHeader>
```json
::: code-group
```json [RP/models/entity/dummy.json]
{
"format_version": "1.12.0",
"minecraft:geometry": [
@@ -119,12 +121,12 @@ If you want to disable collision at all (so you can place a block at it's positi
]
}
```
:::
### Render Controller (Optional)
### 渲染控制器（可选）
<CodeHeader>RP/render_controllers/dummy.json</CodeHeader>
```json
::: code-group
```json [RP/render_controllers/dummy.json]
{
"format_version": "1.10.0",
"render_controllers": {
@@ -140,7 +142,8 @@ If you want to disable collision at all (so you can place a block at it's positi
}
}
```
:::
### Texture (Optional)
### 材质贴图（可选）
You can either leave the texture location blank, or open the model in blockbench and create a blank texture.
可以选择留空材质路径，或者使用Blockbench创建空白材质文件。

435
docs/wiki/3-实体/2-巧思案例/entity-attack.md
View File

@@ -1,6 +1,6 @@
---
title: Entity Attacks
category: Tutorials
title: 实体攻击机制
category: 教程
mentions:
- Luthorius
- TheDoctor15
@@ -9,43 +9,46 @@ mentions:
- epxzzy
- ThomasOrs
tags:
- intermediate
- 中级
---
Entity attacks are a complex subject that require many different things to work correctly:
# 实体攻击机制
- Navigation and movement abilities to move towards its target
- Targeting abilities to pick which entity to attack
- Attack type, such as melee or ranged
- Attack damage and effects
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
## Selecting Targets
实体攻击需要多种系统协同工作才能正确运行：
### Movement
- 导航及移动能力以接近目标
- 目标选择能力以确定攻击对象
- 攻击类型（如近战或远程）
- 伤害数值及附加效果
Before a mob can attack, it will need various [movement components](/entities/entity-movement).
## 目标选择
Before starting to create your entity attacks, you should ensure that your entity can walk around, and navigate its surroundings.
### 移动机制
生物发起攻击前需要搭载多种[移动组件](/entities/entity-movement)。
在开始配置攻击行为前，请确保实体具备基础移动和路径规划能力。
:::warning
Even if you are making an unmoving entity (like turret), you still need to add navigation component, so your entity can find the entity to shoot.
即使要创建固定式防御单位（如炮塔），仍需要添加导航组件以便自动寻找射击目标。
:::
### Triggering Hostility
### 激活敌对行为
There are many ways to trigger hostility. The most common type `nearest_attackable_target`, is shown here. It generally allows you to define which entities this entity is interested in attacking:
触发敌对状态有多种方式。以下为最常用的`nearest_attackable_target`组件示例，主要用于定义实体的主要攻击目标类型：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [原始CodeHeader的值]
"minecraft:behavior.nearest_attackable_target": {
"must_see": true, //If true, potential target must be in mob's line of sight
"reselect_targets": true, //Allows mob to select new target, if one is closer than current
"within_radius": 25.0, //Radius that potential target must be withing
"must_see_forget_duration": 17.0, //If "must_see" = true, time before forgetting target
"must_see": true, //如果为true，目标必须处于实体视线内
"reselect_targets": true, //允许切换更近的目标
"within_radius": 25.0, //有效搜索半径
"must_see_forget_duration": 17.0, //目标消失视野后的记忆时间
"entity_types": [
{
"filters": { //Entities to attack
"filters": { //有效攻击目标筛选
"test": "is_family",
"subject": "other",
"value": "player"
@@ -55,25 +58,25 @@ There are many ways to trigger hostility. The most common type `nearest_attackab
]
}
```
:::
For more fine control, you may also consider using one of the following components:
如需更精细控制，可选用以下组件：
| Component | Note |
| -------------------------------------------------------- | ------------------------------------------------------------ |
| minecraft:behavior.nearest_attackable_target | Targets entity meeting the given requirements |
| minecraft:behavior.nearest_prioritized_attackable_target | Allows for "priority": [integer] to be set after each filter |
| minecraft:behavior.defend_trusted_target | Targets entity that hurts any entities specified in filters |
| 组件 | 说明 |
| ---------------------------------------------------- | ------------------------------------------------------------ |
| minecraft:behavior.nearest_attackable_target | 定位符合筛选条件的实体 |
| minecraft:behavior.nearest_prioritized_attackable_target | 可通过filter后设置"priority": [整数]定义优先级 |
| minecraft:behavior.defend_trusted_target | 防御指定类型的友方单位 |
But there is also one more - `minecraft:lookat`
另有特殊组件`minecraft:lookat`：
This last component is slightly different to the other three, as it is for detecting and targeting entities that attempt eye contact. It is structured like so:
该组件与其他三种不同，用于检测与实体发生视线交互的目标。配置示例：
<CodeHeader>BP/entities/enderman.json</CodeHeader>
```json
::: code-group
```json [BP/entities/enderman.json]
"minecraft:lookat": {
"search_radius": 64.0,
"set_target": true, //Becomes a valid target if true
"set_target": true, //标记为有效目标
"look_cooldown": 5.0,
"filters": {
"all_of": [
@@ -87,24 +90,24 @@ This last component is slightly different to the other three, as it is for detec
"domain": "head",
"subject": "other",
"operator": "not",
"value": "carved_pumpkin" //All players not with carved_pumpkin equipped on head
"value": "carved_pumpkin" //未装备雕刻南瓜的玩家
}
]
}
}
```
### Target selecting
:::tip
This section shows you how to configure the "Targeting" components, explained above.
:::
Mobs find targets by using [filters](https://bedrock.dev/docs/stable/Entities#Filters) can be used to determine which entities are a valid target, through `test`, `subject`, `operator`, and `value`.
### 目标筛选机制
<CodeHeader></CodeHeader>
:::tip
本节说明如何配置上述「目标定位」组件。
:::
```json
实体通过[筛选器](https://bedrock.dev/docs/stable/Entities#Filters)判定有效目标，使用`test`、`subject`、`operator`和`value`参数进行组合判断。
::: code-group
```json [原始CodeHeader的值]
"entity_types":[
{
"filters":{
@@ -121,7 +124,7 @@ Mobs find targets by using [filters](https://bedrock.dev/docs/stable/Entities#Fi
"operator":"==",
"value":"iron_golem"
}
//anything that is equal to either" snow_golem" or "iron_golem"
//雪傀儡或铁傀儡
]
},
"max_dist":24
@@ -142,34 +145,34 @@ Mobs find targets by using [filters](https://bedrock.dev/docs/stable/Entities#Fi
"operator":"=!",
"value":"turtle_helmet"
}
//anything equal to player AND not wearing "turtle_helmet" on head
//未装备海龟盔甲的玩家
]
},
"max_dist":24
}
]
```
:::
This would only target `snow_golem`s, `iron_golem`s, and `player`s that are **not** wearing `turtle_helmet`s.
该配置将锁定雪傀儡、铁傀儡及未佩戴海龟头盔的玩家。
## Types of Attack
## 攻击类型
Here are the available attacks:
可用攻击方式列表：
| Component | Note |
| 组件 | 说明 |
| ---------------------------------------------------- | -------------------------------------------------------- |
| [minecraft:behavior.melee_attack](#melee) | Deals damage to a single target |
| [minecraft:behavior.ranged_attack](#ranged) | Fires a projectile towards a target |
| [minecraft:area_attack](#area) | Effectively melee attacks on anything withing range |
| [minecraft:behavior.knockback_roar](#knockback-roar) | Similar to minecraft:area_attack, but much more flexible |
| [minecraft:behavior.melee_attack](#近战攻击) | 单体近战攻击 |
| [minecraft:behavior.ranged_attack](#远程攻击) | 发射弹射物 |
| [minecraft:area_attack](#范围攻击) | 范围内全体打击 |
| [minecraft:behavior.knockback_roar](#击退怒吼) | 高自定义度的冲击波攻击 |
### Melee
### 近战攻击
Melee attacks are the most common type of attack, they cause knockback, and have a 100% success rate at accuracy.
最常见的攻击类型，带有击退效果且必定命中。
<CodeHeader></CodeHeader>
```json
::: code-group
```json [原始CodeHeader的值]
"wiki:melee_attack": {
"minecraft:attack": {
"damage": 3,
@@ -178,81 +181,81 @@ Melee attacks are the most common type of attack, they cause knockback, and have
},
"minecraft:behavior.melee_attack": {
"priority": 3,
"melee_fov": 90.0, //The allowable FOV the actor will use to determine if it can make a valid melee attack
"melee_fov": 90.0, //实体发动近战攻击时的有效视野角度
"speed_multiplier": 1,
"track_target": false,
"require_complete_path": true
}
}
```
:::
Set the damage, choose a mob effect, and change some additional properties.
可配置伤害数值、状态效果及攻击参数。
The value defined in components stating integers of damage can simply be a constant, or a string containing 2 numbers, for a range of possible values.
伤害数值支持固定值或区间范围：
`"damage": 3` would result in 3 each time
- `"damage": 3`：固定造成3点伤害
- `"damage": [2, 6]`：随机造成2-6点伤害
`"damage": [ 2, 6 ]` would result in any integer between 2 and 6
状态效果支持列表：
Both the mob effect and duration timer are optional, but when they are used, the available effects are as following:
| Effect Name |
| 效果列表 |
| --------------- |
| speed |
| slowness |
| haste |
| mining_fatigue |
| strength |
| instant_health |
| instant_damage |
| jump_boost |
| nausea |
| regeneration |
| resistance |
| fire_resistance |
| water_breathing |
| invisibility |
| blindness |
| night_vision |
| hunger |
| weakness |
| poison |
| wither |
| health_boost |
| absorption |
| saturation |
| levitation |
| fatal_poison |
| slow_falling |
| conduit_power |
| bad_omen |
| village_hero |
| darkness |
| 速度 |
| 缓慢 |
| 急迫 |
| 挖掘疲劳 |
| 力量 |
| 瞬间治疗 |
| 瞬间伤害 |
| 跳跃提升 |
| 反胃 |
| 生命恢复 |
| 抗性提升 |
| 防火 |
| 水下呼吸 |
| 隐身 |
| 失明 |
| 夜视 |
| 饥饿 |
| 虚弱 |
| 中毒 |
| 凋零 |
| 生命提升 |
| 伤害吸收 |
| 饱和 |
| 飘浮 |
| 剧毒 |
| 缓降 |
| 潮涌能量 |
| 不祥之兆 |
| 村庄英雄 |
| 黑暗 |
### Ranged
### 远程攻击
Fires specified [projectiles](/documentation/projectiles) towards target at set intervals.
按设定间隔发射指定[弹射物](/documentation/projectiles)。
<CodeHeader></CodeHeader>
```json
::: code-group
```json [原始CodeHeader的值]
"wiki:ranged_attack": {
"minecraft:behavior.ranged_attack": {
"priority": 2,
"ranged_fov": 90.0, //The allowable FOV the actor will use to determine if it can make a valid ranged attack
"attack_interval_min": 1.0,
"attack_interval_max": 3.0,
"attack_radius": 15.0
"ranged_fov": 90.0, //实体发动远程攻击时的有效视野角度
"attack_interval_min": 1.0, //最小攻击间隔
"attack_interval_max": 3.0, //最大攻击间隔
"attack_radius": 15.0 //攻击范围
},
"minecraft:shooter": {
"def": "wiki:projectile"
"def": "wiki:projectile" //自定义弹射物定义
}
}
```
:::
List of vanilla projectiles:
原版弹射物类型：
| Vanilla Projectiles |
| 原版弹射物 |
| -------------------------------- |
| minecraft:arrow |
| minecraft:dragon_fireball |
@@ -271,33 +274,32 @@ List of vanilla projectiles:
| minecraft:wither_skull_dangerous |
| minecraft:xp_bottle |
Only one item has an effect on an entity's ranged attacks. Crossbows. If one is equipped, it is first required for it to be "charged" before the entity can fire anything. Regardless of the projectile stated in `minecraft:shooter`, the item to charge the crossbow with should always be `minecraft:arrow`.
弩类武器需先装填后发射：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [原始CodeHeader的值]
"minecraft:behavior.charge_held_item": {
"priority": 2,
"items": [
"minecraft:arrow"
"minecraft:arrow" //弩的弹药类型固定为箭
]
}
```
:::
Once `minecraft:behavior.charge_held_item` has been achieved, the entity will be able to execute the process of `minecraft:behavior.ranged_attack`, and will then need to charge again.
完成装填后方可触发`minecraft:behavior.ranged_attack`。
### Area
### 范围攻击
These attacks damage all entities within a set radius. It is different to both ranged and melee in that this component doesn’t actually require a target. Regardless of the entities behaviour, _all_ entities will be affected by this. It appears to be similar to melee attacks, as it deals knockback in a similar manner, though dealing damage at a constant rate.
对范围内的所有实体造成伤害。与常规攻击不同，无需特定目标即可触发。
<CodeHeader></CodeHeader>
```json
::: code-group
```json [原始CodeHeader的值]
"minecraft:area_attack" : {
"damage_range": 1, //distance in blocks
"damage_per_tick": 2,
"cause": "contact",
"entity_filter": {
"damage_range": 1, //伤害作用范围（方块）
"damage_per_tick": 2, //每tick伤害量
"cause": "contact", //伤害来源类型
"entity_filter": { //有效目标筛选
"any_of": [
{
"test": "is_family",
@@ -313,58 +315,58 @@ These attacks damage all entities within a set radius. It is different to both r
}
}
```
:::
[Entity damage sources](https://bedrock.dev/docs/stable/Addons#Entity%20Damage%20Source). It is important to take these into consideration, as certain items in vanilla can protect from some, like armour enchantments, and you can also make mobs immune to specific sources using `minecraft:damage_sensor`.
需参考[实体伤害源类型](https://bedrock.dev/docs/stable/Addons#Entity%20Damage%20Source)进行配置，注意部分原版装备可减免特定类型伤害。
### Knockback Roar
### 击退怒吼
Many similarities between this and `minecraft:area_attack`, this component though having much more flexibility.
高灵活性范围攻击，可产生冲击波效果。
<CodeHeader></CodeHeader>
```json
::: code-group
```json [原始CodeHeader的值]
"wiki:roar_attack": {
"minecraft:behavior.knockback_roar":{
"priority":2,
"duration":0.7,
"attack_time":0.2,
"knockback_damage":1,
"knockback_horizontal_strength":1,
"knockback_vertical_strength":1,
"knockback_range":5,
"knockback_filters":{
"duration":0.7, //技能总时长
"attack_time":0.2, //实际造成伤害时间点
"knockback_damage":1, //击退伤害
"knockback_horizontal_strength":1, //水平击退力度
"knockback_vertical_strength":1, //垂直击退力度
"knockback_range":5, //作用范围
"knockback_filters":{ //击退目标筛选
"test":"is_family",
"subject":"other",
"operator":"==",
"value":"player"
},
"damage_filters":{
"damage_filters":{ //伤害目标筛选
"test":"is_family",
"subject":"other",
"operator":"==",
"value":"player"
},
"on_roar_end":{
"on_roar_end":{ //技能结束触发事件
"event":"wiki:other_event"
},
"cooldown_time":10
"cooldown_time":10 //冷却时间
}
}
```
:::
This is more like a shockwave of damage. Extremely versatile in uses. Produces a particle effect, which can be disabled by adding a modified version of `knockback_roar.json` to a resource pack's particles folder.
若需要隐藏默认粒子效果，可在资源包中覆盖相关粒子文件。
## More on Attacks
## 进阶攻击配置
Entity Attacks don't have to be as simple as Mob being hostile towards X target, doing X attack, dealing X damage.
攻击行为可通过事件系统进行更高级的交互设计。
### Difficulty Dependant Attacks
### 难度分级攻击
Express components and values to use for each difficulty.
不同游戏难度配置不同攻击参数：
<CodeHeader>BP/entities/bee.json</CodeHeader>
```json
::: code-group
```json [BP/entities/bee.json]
"easy_attack": {
"minecraft:attack": {
"damage": 2
@@ -385,18 +387,23 @@ Express components and values to use for each difficulty.
}
}
```
:::
### Switching Modes
### 模式切换系统
You can use events to make your mob only attack under specific circumstances, or swap between the different types of attack. This can be achieved through simple usage of [events](/entities/entity-events) and component groups. Two prime examples being `minecraft:environment_sensor` and `minecraft:target_nearby_sensor`. The two are pretty similar in regards of structure, difference being that one is for sensing environments and the other for testing for target distance.
通过[事件系统](/entities/entity-events)和组件组实现攻击模式切换。常用传感器组件：
#### Attacks
| 传感器类型 | 说明 |
| ---------------------- | ----------------------- |
| minecraft:environment_sensor | 环境条件监测 |
| minecraft:target_nearby_sensor | 目标距离监测 |
Component groups are required to define the different modes of attack, such as:
#### 组件组示例
<CodeHeader></CodeHeader>
远程攻击配置组：
```json
::: code-group
```json [原始CodeHeader的值]
"wiki:ranged_components": {
"minecraft:shooter": {
"def": "wiki:projectile"
@@ -410,10 +417,12 @@ Component groups are required to define the different modes of attack, such as:
}
}
```
:::
<CodeHeader></CodeHeader>
近战攻击配置组：
```json
::: code-group
```json [原始CodeHeader的值]
"wiki:melee_components": {
"minecraft:attack": {
"damage": 6
@@ -423,85 +432,41 @@ Component groups are required to define the different modes of attack, such as:
}
}
```
:::
Those are examples of your attack modes, but they are not the only ones you can use. `wiki:ranged_components` and `wiki:melee_components` are generic names for the components within them, they can have any name, but it's what's nested inside them that counts.
#### 事件触发器
#### Events
距离传感器示例：
These component groups won't actually do anything by themselves. Another component group is required, and some events to add/remove the attack modes.
<CodeHeader></CodeHeader>
```json
"wiki:melee_swap": { //When triggered, adds component group for ranged and removes melee component group
"remove": {
"component_groups": [
"wiki:ranged_components"
]
},
"add": {
"component_groups": [
"wiki:melee_components"
]
}
}
```
<CodeHeader></CodeHeader>
```json
"wiki:ranged_swap": { //When triggered, adds component group for melee and removes ranged component group
"remove": {
"component_groups": [
"wiki:melee_components"
]
},
"add": {
"component_groups": [
"wiki:ranged_components"
]
}
}
```
The events are effectively for just turning attack modes on and off, by adding and removing different component groups.
#### Sensors
To trigger the events, another component group is used. Sensors are components that can trigger events when certain conditions are fulfilled. Here are 2 examples of different sensors:
- For sensing the distance between the mob and target
<CodeHeader></CodeHeader>
```json
::: code-group
```json [原始CodeHeader的值]
"wiki:switcher_range": {
"minecraft:target_nearby_sensor": {
"inside_range": 4.0,
"outside_range": 5.0,
"must_see": true,
"on_inside_range": { //When target is within 4 blocks range, trigger "wiki:melee_swap" event
"on_inside_range": { //4格内切换近战
"event": "wiki:melee_swap",
"target": "self"
},
"on_outside_range": { //When target is beyond 5 blocks range, trigger "wiki:ranged_swap" event
"on_outside_range": { //5格外切换远程
"event": "wiki:ranged_swap",
"target": "self"
}
}
}
```
:::
- For sensing certain features of the environment of which the mob is exposed to
环境传感器示例：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [原始CodeHeader的值]
"wiki:switcher_environment": {
"minecraft:environment_sensor": {
"triggers": [
{
"filters": { //When underwater, trigger "wiki:melee_swap" event
{ //水下转为近战
"filters": {
"test": "is_underwater",
"subject": "self",
"operator": "==",
@@ -509,8 +474,8 @@ To trigger the events, another component group is used. Sensors are components t
},
"event": "wiki:melee_swap"
},
{
"filters": { //When not underwater, trigger "wiki:ranged_swap" event
{ //陆地转为远程
"filters": {
"test": "is_underwater",
"subject": "self",
"operator": "==",
@@ -522,49 +487,39 @@ To trigger the events, another component group is used. Sensors are components t
}
}
```
This uses `Filters`, similar to how the [target is initially selected](#target-selecting).
:::tip
You aren't limited to just 2 attack types, you can have as many as you want! Just make sure to have the event's and sensors to compensate for them.
:::
## Visual Animations
:::tip
攻击类型切换不限于两种模式，可根据需求扩展更多。
:::
Attacks and animations go hand in hand. Within resource packs, the following 3 directories are required:
## 动作表现配置
- animations (entityname.animation.json)
- animation_controllers (entityname.animation_controller.json)
- entity (entityname.json)
攻击需配合动画系统实现完整表现。
Or as long as you know the names of vanilla animations and animation controllers, you can define them in the latter directory and folder.
### 动画资源
### Animations
建议使用[Blockbench](/guide/blockbench)制作动画，需在资源包中包含：
Animations are self explanatory. The files themselves contain all specific animations for the given entity. The recommended way to make animations is by using [blockbench](/guide/blockbench).
- animations文件夹（实体动画定义）
- animation_controllers文件夹（动画控制器）
- entity文件夹（实体定义）
Though it is possible to create them in a simple text editor.
| Vanilla Attack Animations |
| 原版攻击动画 |
| -------------------------------------------- |
| "animation.zombie.attack_bare_hand" |
| "animation.skeleton.attack.v1.0" |
| "animation.humanoid.bow_and_arrow.v1.0" |
| "animation.humanoid.damage_nearby_mobs.v1.0" |
A few examples of Animations. Locate /vanilla_resource_pack/animations for all of them.
### 动画控制器
### Animation Controllers
控制动画的触发逻辑：
List of states that trigger animations.
| Vanilla Attack Animation Controllers |
| 原版动画控制器 |
| ---------------------------------------------- |
| "controller.animation.zombie.attack_bare_hand" |
| "controller.animation.skeleton.attack" |
| "controller.animation.humanoid.bow_and_arrow" |
| "controller.animation.humanoid.attack" |
A few examples of Animation Controllers. Locate /vanilla_resource_pack/animation_controllers for all of them
More information on animations can be found [here](https://bedrock.dev/docs/stable/Animations).
更多动画系统细节请参考[官方文档](https://bedrock.dev/docs/stable/Animations)。

56
docs/wiki/3-实体/2-巧思案例/entity-holds-item.md
View File

@@ -1,8 +1,8 @@
---
title: Entity Holds Item
category: Tutorials
title: 实体手持物品
category: 教程
tags:
- intermediate
- 中等难度
mentions:
- pieterdefour
- SirLich
@@ -15,46 +15,49 @@ mentions:
- 7dev7urandom
---
# 实体手持物品
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
::: tip
This tutorial assumes you have a basic understanding of entities, loot tables, and Blockbench.
本教程假设您已对实体、战利品表和Blockbench有基本了解。
:::
In this tutorial, you will learn to have an entity spawn with an item in its hand. I'll be using a custom `mandalorian_armorer` entity and a custom `hammer` item for the examples.
在本教程中，您将学习如何让实体生成时手持物品。示例中将使用自定义实体 `mandalorian_armorer` 和自定义物品 `hammer`。
## Model
## 模型
First of all, you'll need to have a model in Blockbench that has a map called `rightArm`. Within this map, there needs to be a submap called 'rightItem'.
Now set the position of the pivot point of this submap, so it sits in the place you want the entity to hold the item at.
首先需要在Blockbench中创建包含名为 `rightArm` 骨架的模型。该骨架内必须包含名为 `rightItem` 的子骨架。
将该子骨架的枢轴点定位至您期望实体手持物品的位置。
![](/assets/images/tutorials/entity-holds-item/blockbench.png)
## Behavior Pack-side
## 行为包配置
Now you'll need to add a `minecraft:equipment` component in the component list for your entity and add a loot table with the desired item.
接下来需在实体的组件列表中添加 `minecraft:equipment` 组件，并配置包含目标物品的战利品表。
In our example it will look like this:
示例配置如下：
<CodeHeader>BP/entity/mandolorian.json#components</CodeHeader>
```json
::: code-group
```json [BP/entity/mandolorian.json#components]
"minecraft:equipment": {
"table": "loot_tables/entities/gear/mandolorian.json"
}
```
## Loot Table
Finally, add the loot table for your entity. It needs to be in `loot_tables/entities/<your_loot_table_name>.json` in the behavior pack. In our case, it's called `mandolorian.json`.
:::warning
This isn't the same loot table as what it drops on death. So make sure it has a different name.
:::
To have the entity always spawn with the same item, add the following loot table:
## 战利品表配置
<CodeHeader>BP/loot_tables/entities/gear/mandolorian.json</CodeHeader>
最后在行为包的 `loot_tables/entities/<你的战利品表名称>.json` 路径下添加对应战利品表。本示例中文件名为 `mandolorian.json`。
```json
:::warning
此战利品表与生物死亡掉落表不同，请确保使用不同命名。
:::
要让实体始终持握特定物品，按照以下格式配置战利品表：
::: code-group
```json [BP/loot_tables/entities/gear/mandolorian.json]
{
"pools": [
{
@@ -70,7 +73,8 @@ To have the entity always spawn with the same item, add the following loot table
]
}
```
:::
If everything went well, you'd have something looking like this:
成功配置后，效果应如下图所示：
![](/assets/images/tutorials/entity-holds-item/finished_result.png)
![](/assets/images/tutorials/entity-holds-item/finished_result.png)

191
docs/wiki/3-实体/2-巧思案例/entity-movement.md
View File

@@ -1,6 +1,6 @@
---
title: Entity Movement
category: Tutorials
title: 实体移动
category: 教程
mentions:
- SirLich
- sermah
@@ -8,138 +8,126 @@ mentions:
- TheDoctor15
---
In Minecraft, entities have the ability to move through the world, either by walking, swimming or flying. To get these behaviors, your entity will generally need quite a few behaviors, broken out into various types.
# 实体移动
As you read this tutorial, keep in mind that your entity will need at least:
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
- [A component that sets the entities movement speed.](#movement-speed)
- [A component to set how the entity will move (walking, flying, etc)](#movement-type)
- [A component to set the entities navigation abilities, so it can generate paths.](#navigation-abilities)
- [A component that sets where/when the entity should move (AI Goals).](#ai)
在Minecraft中，实体可以通过行走、游泳或飞行的方式在世界中移动。要为实体赋予这些行为能力，通常需要配置多种不同类型的组件。
阅读本教程时请注意，您的实体至少需要以下组件：
- [设置移动速度的基础组件](#移动速度)
- [定义移动方式的组件（行走/飞行等）](#移动方式)
- [设定导航能力的组件，用于生成移动路径](#导航能力)
- [控制实体移动时机和方向的AI组件](#人工智能)
:::tip
The best way to create a moving entity is by picking a similar entity from the vanilla behavior pack, and copying the components into your entity.
创建移动实体的最佳方式是从原版行为包中找到类似实体，将其组件配置复制到您的实体中。
For example entities like Phantom, or Ghast, or Parrot are all flying entities, but have very different in-game behavior! Use the closest-matching entity as a template.
例如像夜魅（Phantom）、恶魂（Ghast）或鹦鹉这类飞行实体，虽然具有完全不同的游戏行为，但它们都是通过基本相似的组件实现移动功能的。建议选择与目标实体最接近的原版生物作为模板。
:::
## Movement Speed
## 移动速度
The first thing your entity needs is a speed component. This sets how quickly your entity will move through the world.
首先需要为实体配置移动速度组件，这些参数决定了实体在世界中的移动快慢。
| Component | Note |
| ---------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| [minecraft:movement](/entities/vanilla-usage-components#movement) | Set movement speed (required) |
| [minecraft:underwater_movement](/entities/vanilla-usage-components#underwater-movement) | Set movement speed in the water. |
| [minecraft:flying_speed](/entities/vanilla-usage-components#flying-speed) | Set the speed in the air. |
| 组件 | 说明 |
| ---------------------------------------------------------------------------------------------------- | ----------------------------- |
| [minecraft:movement](/entities/vanilla-usage-components#movement) | 设置基础移动速度（必需组件） |
| [minecraft:underwater_movement](/entities/vanilla-usage-components#underwater-movement) | 设置水下移动速度 |
| [minecraft:flying_speed](/entities/vanilla-usage-components#flying-speed) | 设置空中飞行速度 |
You should always include `minecraft:movement`. Add the other two as needed.
所有实体必须包含`minecraft:movement`组件。其他两个组件按需添加。
All vanilla "swimming" entities like Dolphin include `underwater_movement`. Only some flying entities have `flying_speed`. It is not known why this is the case.
原版水中生物（如海豚）都包含`underwater_movement`组件。部分飞行生物具有`flying_speed`组件（具体配置因生物而异）。
## Movement Type
## 移动方式
Your entity will also need a movement type. Movement types set hard-coded behavior for _how_ your entity will move through the world.
实体需要配置移动类型组件来定义其基础运动模式。注意每个实体只能选择一种移动类型，请根据实际需求选择最匹配的类型。
You may only include one movement type in your entity. Select the component that most closely matches your needs. Generally `basic`, `amphibious` and `fly` are good ones to use.
| 组件 | 说明 |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [minecraft:movement.amphibious](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.amphibious) | 两栖移动模式，允许同时在水中游泳和陆地行走 |
| [minecraft:movement.basic](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.basic) | 基础移动模式 |
| [minecraft:movement.fly](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.fly) | 飞行移动模式 |
| [minecraft:movement.generic](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.generic) | 通用移动模式，支持多种移动能力 |
| [minecraft:movement.hover](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.hover) | 悬停移动模式 |
| [minecraft:movement.jump](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.jump) | 跳跃移动模式，可配置跳跃间隔时间 |
| [minecraft:movement.skip](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.skip) | 蹦跳移动模式 |
| [minecraft:movement.sway](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.sway) | 摆动移动模式，模拟水生生物游动姿态 |
| Component | Note |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [minecraft:movement.amphibious](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.amphibious) | This move control allows the mob to swim in the water and walk on land. |
| [minecraft:movement.basic](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.basic) | This component accents the movement of an entity. |
| [minecraft:movement.fly](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.fly) | This move control causes the mob to fly. |
| [minecraft:movement.generic](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.generic) | This move control allows a mob to fly, swim, climb, etc. |
| [minecraft:movement.hover](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.hover) | This move control causes the mob to hover. |
| [minecraft:movement.jump](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.jump) | Move control causes the mob to jump as it moves with a specified delay between jumps. |
| [minecraft:movement.skip](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.skip) | This move control causes the mob to hop as it moves. |
| [minecraft:movement.sway](https://bedrock.dev/docs/stable/Entities#minecraft%3Amovement.sway) | This move control causes the mob to sway side to side, giving the impression it is swimming. |
## 移动修正
## Movement Modifiers
下列组件可为实体移动提供额外的物理效果调整，常规情况下不是必须组件，但需要了解其功能。
Movement modifiers provide additional information about how your entity will move through the world. These components are not required for normal entities, but you should be aware of them.
| 组件 | 说明 |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| [minecraft:water_movement](https://bedrock.dev/docs/stable/Entities#minecraft%3Awater_movement) | 设置实体在水中的摩擦力 |
| [minecraft:rail_movement](https://bedrock.dev/docs/stable/Entities#minecraft%3Arail_movement) | 使实体能够沿轨道移动（限轨道移动） |
| [minecraft:friction_modifier](https://bedrock.dev/docs/stable/Entities#minecraft%3Afriction_modifier) | 设置实体陆地移动摩擦力 |
| Component | Note |
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| [minecraft:water_movement](https://bedrock.dev/docs/stable/Entities#minecraft%3Awater_movement) | Sets the friction the entity experiences in water. |
| [minecraft:rail_movement](https://bedrock.dev/docs/stable/Entities#minecraft%3Arail_movement) | Sets that the entity can move on rails (only). |
| [minecraft:friction_modifier](https://bedrock.dev/docs/stable/Entities#minecraft%3Afriction_modifier) | Sets the friction the entity experiences on land. |
## 导航能力
## Navigation
The next thing your entity needs is a navigation component. Navigation components have quite a few fields, like whether the entity can open doors or avoid sunlight. How you set these fields is generally more important than the navigation component you pick!
The reason there are so many navigation components is that each one gives a slightly different hard-coded behavior. Pick the navigation component whose name/description best matches the kind of navigation your entity will be doing.
You can only have one navigation component at any given time.
导航组件定义了路径生成规则。每个导航组件都有独特的硬编码逻辑，需要根据实体的具体需求选择最匹配的类型。
:::tip
This component is very important. You should check vanilla examples for inspiration on what fields and values to use.
此组件对实体行为影响重大，建议参考原版生物的配置获取启发
:::
| Component | Note |
| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [minecraft:navigation.climb](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.climb) | Allows this entity to generate paths that include vertical walls like the vanilla Spiders do. |
| [minecraft:navigation.float](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.float) | Allows this entity to generate paths by flying around the air like the regular Ghast. |
| [minecraft:navigation.generic](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.generic) | Allows this entity to generate paths by walking, swimming, flying and climbing around, and jumping up and down a block. |
| [minecraft:navigation.fly](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.fly) | Allows this entity to generate paths in the air as the vanilla Parrots do. |
| [minecraft:navigation.swim](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.swim) | Allows this entity to generate paths that include water. |
| [minecraft:navigation.walk](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.walk) | Allows this entity to generate paths by walking around and jumping up and down a block like regular mobs. |
| 组件 | 说明 |
| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [minecraft:navigation.climb](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.climb) | 允许生成墙面路径（类似蜘蛛的爬墙能力） |
| [minecraft:navigation.float](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.float) | 允许空中漂浮移动（类似恶魂的移动方式） |
| [minecraft:navigation.generic](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.generic) | 通用导航模式，支持行走、游泳、飞行和攀爬等多种路径生成 |
| [minecraft:navigation.fly](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.fly) | 空中飞行导航（类似鹦鹉的飞行路径计算） |
| [minecraft:navigation.swim](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.swim) | 水体环境导航 |
| [minecraft:navigation.walk](https://bedrock.dev/docs/stable/Entities#minecraft%3Anavigation.walk) | 标准行走导航（类似普通生物的移动逻辑） |
## Navigation Abilities
## 增强组件
On top of the movement and the navigation component, there exist many additional components to augment the abilities of your entity as they move through the world.
以下是增强实体移动能力的可选组件：
| Component | Note |
| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [minecraft:annotation.break_door](https://bedrock.dev/docs/stable/Entities#minecraft%3Aannotation.break_door) | Allows entity to break doors. It must also be turned on in the navigation component. |
| [minecraft:annotation.open_door](https://bedrock.dev/docs/stable/Entities#minecraft%3Aannotation.open_door) | Allows entity to open doors. It must also be turned on in the navigation component. |
| [minecraft:buoyant](https://bedrock.dev/docs/stable/Entities#minecraft%3Abuoyant) | Specifies which liquids the entity can float in. |
| [minecraft:can_climb](https://bedrock.dev/docs/stable/Entities#minecraft%3Acan_climb) | Allows this entity to climb up ladders. |
| [minecraft:can_fly](https://bedrock.dev/docs/stable/Entities#minecraft%3Acan_fly) | Marks the entity as being able to fly. The pathfinder won't be restricted to paths where a solid block is required underneath it. |
| [minecraft:can_power_jump](https://bedrock.dev/docs/stable/Entities#minecraft%3Acan_power_jump) | Allows the entity to power jump like the horse does in vanilla. |
| [minecraft:floats_in_liquid](https://bedrock.dev/docs/stable/Entities#minecraft%3Afloats_in_liquid) | Sets that this entity can float in liquid blocks. |
| [minecraft:jump.dynamic](https://bedrock.dev/docs/stable/Entities#minecraft%3Ajump.dynamic) | Defines a dynamic type jump control that will change jump properties based on the speed modifier of the mob. |
| [minecraft:jump.static](https://bedrock.dev/docs/stable/Entities#minecraft%3Ajump.static) | Gives the entity the ability to jump. |
| 组件 | 说明 |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [minecraft:annotation.break_door](https://bedrock.dev/docs/stable/Entities#minecraft%3Aannotation.break_door) | 允许实体破坏门（需同时在导航组件中启用） |
| [minecraft:annotation.open_door](https://bedrock.dev/docs/stable/Entities#minecraft%3Aannotation.open_door) | 允许实体开门（需同时在导航组件中启用） |
| [minecraft:buoyant](https://bedrock.dev/docs/stable/Entities#minecraft%3Abuoyant) | 指定实体可以漂浮的液体类型 |
| [minecraft:can_climb](https://bedrock.dev/docs/stable/Entities#minecraft%3Acan_climb) | 允许实体攀爬梯子 |
| [minecraft:can_fly](https://bedrock.dev/docs/stable/Entities#minecraft%3Acan_fly) | 标记实体飞行能力（导航系统不会强制要求踏板支撑） |
| [minecraft:can_power_jump](https://bedrock.dev/docs/stable/Entities#minecraft%3Acan_power_jump) | 允许进行强力跳跃（类似马匹的跳跃机制） |
| [minecraft:floats_in_liquid](https://bedrock.dev/docs/stable/Entities#minecraft%3Afloats_in_liquid) | 使实体能够在液体中漂浮 |
| [minecraft:jump.dynamic](https://bedrock.dev/docs/stable/Entities#minecraft%3Ajump.dynamic) | 根据移动速度自动调整跳跃属性 |
| [minecraft:jump.static](https://bedrock.dev/docs/stable/Entities#minecraft%3Ajump.static) | 赋予实体基本的跳跃能力 |
There are also components like `minecraft:preferred_path`, which will modify navigation based on block-based path-cost.
## 人工智能
## AI Goals
导航组件定义了移动方式，而AI目标组件决定移动的时机和目的地。AI目标通过优先级系统（数值越低优先级越高）控制行为选择。
The navigation component tells the entity _how_ to generate paths, but it doesn't say _when_ or _where_ to generate paths. This is what the AI components are for.
通常需要叠加多个不同优先级的AI组件来形成自然的行为模式。以下为部分常用AI组件示例：
AI Goals are prefixed with `behavior` and follow a priority system to pick which behavior to run. The lower priorities will be picked first.
In general, you should usually add quite a few AI components, with different priorities. Layered together, these will create realistic movement and behavior for your entity. As always, vanilla entities provide a good template for which components to add, and with what properties/priorities.
There are too many AI components that generate paths to list in this document. A few will be provided as examples:
| Component |
| --------------------------------------------------------------------------------------------------------------------------------- |
| 组件 |
| ---------------------------------------------------------------------------------------------------------------------------- |
| [minecraft:behavior.random_stroll](https://bedrock.dev/docs/stable/Entities#minecraft%3Abehavior.random_stroll) |
| [minecraft:behavior.follow_owner](https://bedrock.dev/docs/stable/Entities#minecraft%3Abehavior.follow_owner) |
| [minecraft:behavior.move_to_water](https://bedrock.dev/docs/stable/Entities#minecraft%3Abehavior.move_to_water) |
| [minecraft:behavior.stroll_towards_village](https://bedrock.dev/docs/stable/Entities#minecraft%3Abehavior.stroll_towards_village) |
For a full list, visit [bedrock.dev](https://bedrock.dev/docs/stable/Entities#AI%20Goals).
完整列表请访问[基岩开发文档](https://bedrock.dev/docs/stable/Entities#AI%20Goals)。
### Pathfinding
### 路径规划
Making entities go to specific places is one of the most common requests for Marketplace content.
The best way to do pathfinding uses a second entity, which the first entity will be attracted to. I am going to call this secondary entity the **marker**. If you are confused on how to create a marker, visit the [Dummy Entities](/entities/dummy-entities) page.
实现实体自动寻路是常用需求。推荐使用通过"诱饵实体"（Marker）进行引导的方案。若需要创建诱饵实体，请参考[虚拟实体教程](/entities/dummy-entities)。
#### Idea
#### 实现思路
The way we are going to do pathfinding is actually fairly simple: Make our entity aggressive towards our marker, and then simply place our marker where we want our entity to path to. The hard part is knowing what components to add so we get really long-range pathing.
基本原理是使主实体对诱饵实体产生敌对行为，通过放置诱饵实体引导主实体移动。关键点在于配置正确的组件参数以实现长距离寻路。
#### Components
#### 组件配置
These components can be edited as needed to create good pathing. Make sure to update the `nearest_attackable_target` to point to your marker entity. This takes a `family_type`, so you should set one of those on your marker.
以下配置中需要将`nearest_attackable_target`指向虚体诱饵（需要为诱饵实体设置family_type属性）。同时不要忘记添加常规的移动和导航组件。
Don't forget to add some basic movement and navigation components so your entity is able to move.
<CodeHeader></CodeHeader>
```json
::: code-group
```json [标记目标锁定]
"minecraft:behavior.nearest_attackable_target": {
"priority": 0,
"reselect_targets": true,
@@ -172,14 +160,14 @@ Don't forget to add some basic movement and navigation components so your entity
"max": 1000
}
```
:::
#### Detecting a reached waypoint
#### 航点到达检测
You can use `minecraft:target_nearby_sensor` to detect when you have reached the marker entity:
使用目标临近传感器检测是否到达标记位置：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [临近传感器]
"minecraft:target_nearby_sensor": {
"inside_range": 2.0,
"outside_range": 4.0,
@@ -192,11 +180,12 @@ You can use `minecraft:target_nearby_sensor` to detect when you have reached the
}
}
```
:::
## Other
## 其他技巧
:::tip
You can trigger entity walking animation via command.
可通过命令强制触发实体行走动画：
`/execute as @e[type=...] at @s run tp @s ^^^0.1`
This way you can control where entity goes and make it look natural.
:::
使用这种方式可以实现对实体移动路径的精确控制，并保持自然的动画效果。
:::

141
docs/wiki/3-实体/2-巧思案例/flying-entities.md
View File

@@ -1,9 +1,9 @@
---
title: Flying Entities
category: Tutorials
title: 飞行实体的控制方法
category: 教程
tags:
- recipe
- intermediate
- 配方
- 中级
mentions:
- SirLich
- Joelant05
@@ -16,39 +16,42 @@ mentions:
- TheItsNameless
---
Whether making a plane or a dragon, adding controllability to flying entities will probably challenge most devs who haven't dabbled around this concept. Since there is no "right" way of adding a piloting mechanic to flying entities, I'll showcase 3 main workaround ways you can use to achieve this.
# 飞行实体的控制方法
## Great Jump, Slow Fall
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
While not exactly "flying", setting the entity's jumping power high and giving it slow falling & speed effects as it falls is probably the most straightforward method.
无论是制作飞机还是飞龙，为飞行实体添加可控性对于未接触过此类概念的开发者来说都具有挑战性。由于没有"标准"方法来实现飞行操控，本文将展示三种主要的替代方案。
To achieve this, we will need to add the `"minecraft:horse.jump_strength"` component to our entity. Adding this will allow you to control its jumping power and disable dismounting when the player presses the jump button.
## 高跳缓降法
<CodeHeader></CodeHeader>
虽然不算严格意义上的"飞行"，但通过设置实体高跳跃能力并附加缓降和加速效果是最直接的方式。
```json
需要给实体添加 `"minecraft:horse.jump_strength"` 组件，该组件可控制跳跃高度并禁用跳跃键下马功能。
::: code-group
```json [组件配置]
"minecraft:horse.jump_strength": {
"value": 7
}
```
:::
We can also use `"value"` as an object to utilize the **range bar** players will see when holding down the jump button.
使用范围值对象可显示蓄力进度条：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [蓄力进度条配置]
"minecraft:horse.jump_strength": {
"value": { "range_min": 0.6, "range_max": 1.2 }
}
```
:::
Now we will give it slow falling and speed as it's falling so that it doesn't instantly fall. To do this, we will make an animation controller and give it those effects when it's not on the ground as so:
通过动画控制器在空中时附加缓降和加速效果：
(You can read a tutorial on how to use animation controllers to execute commands [here](/animation-controllers/entity-commands).)
（可参考[实体命令动画控制器教程](/animation-controllers/entity-commands)）
<CodeHeader></CodeHeader>
```json
::: code-group
```json [动画控制器]
"controller.animation.dragon.flying":{
"states":{
"default":{
@@ -75,12 +78,12 @@ Now we will give it slow falling and speed as it's falling so that it doesn't in
}
}
```
:::
We'll also need to hook it up to our entity as so:
实体描述符需关联控制器：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [实体配置]
"description":{
"identifier":"wiki:dragon",
"is_spawnable":true,
@@ -96,20 +99,18 @@ We'll also need to hook it up to our entity as so:
}
}
```
:::
Now, we should have a mechanic at least resemblant of flying. You can change the values like jump_strength and speed, but the entity will always fall using this method.
通过调整跳跃力度和速度参数可改变飞行体验，但实体最终仍会下落。
## Controlling Through Looking
## 视角控制法
This is probably the most popular method of piloting flying entities, and unlike the first method, this one gives players control over the vertical movement of the entity so that you don't always have to fall every time you jump, with the downside being you can't look around freely without changing the entity's vertical trajectory.
这是最流行的飞行控制方式，通过检测玩家俯仰角来控制垂直运动。优点是可主动控制升降，缺点是视角转动会影响飞行轨迹。
This method detects the riding player's vertical rotation and applies levitation/slow_falling effects to the entity accordingly.
使用命令方块检测玩家垂直视角并应用飘浮/缓降效果：
There are multiple ways of achieving that, but in this tutorial, we'll be using the target selectors `rym` (minimum y-rotation) and `ry` (maximum y-rotation) in a chain of repeating command-blocks to detect the player's pitch, and depending on the range, giving our entity levitation or slowly falling.
<CodeHeader></CodeHeader>
```
::: code-group
```mcfunction
execute @a[rxm=-90,rx=-25] ~~~ effect @e[type=wiki:dragon,r=1] levitation 1 6 true
execute @a[rxm=-25,rx=-15] ~~~ effect @e[type=wiki:dragon,r=1] levitation 1 3 true
execute @a[rxm=-15,rx=-5] ~~~ effect @e[type=wiki:dragon,r=1] levitation 1 2 true
@@ -117,17 +118,14 @@ execute @a[rxm=-5,rx=20] ~~~ effect @e[type=wiki:dragon,r=1] levitation 1 1 true
execute @a[rxm=20,rx=35] ~~~ effect @e[type=wiki:dragon,r=1] slow_falling 1 1 true
execute @a[rxm=35,rx=90] ~~~ effect @e[type=wiki:dragon,r=1] clear
```
:::
**Depending on how big your entity is and how far away the player's seat is from its pivot, you might need to change the radius `r` to a more significant value.**
**注意：根据实体尺寸和坐骑点位置可能需要调整选择器半径 `r` 的数值**
After you run those commands in a repeating command block, you should control its vertical movement by looking up and down.
or you may use a simple animation controller and link it to the entity, so it always plays the function.
建议通过动画控制器关联玩家实现持续效果：
It's recommended that you link this animation controller to the player.
<CodeHeader></CodeHeader>
```json
::: code-group
```json [玩家动画控制器]
{
"format_version": "1.10.0",
"animation_controllers": {
@@ -159,12 +157,12 @@ It's recommended that you link this animation controller to the player.
}
}
```
:::
The entity will probably still be too slow when flying, so we'll borrow our animation controller from the first method with some changes to give the entity speed when it's flying.
通过改良版动画控制器维持飞行速度:
<CodeHeader></CodeHeader>
```json
::: code-group
```json [改良版速度控制器]
"controller.animation.dragon.flying":{
"states":{
"default":{
@@ -213,14 +211,12 @@ The entity will probably still be too slow when flying, so we'll borrow our anim
}
}
```
:::
_Since the entity's effects might be cleared when it's being flown, we changed the animation controller to give the entity speed every tick it's not on the ground._
添加骑乘检测标签来优化误触发问题：
You might also notice that the entity levitates when you go near it. We can fix this by giving the entity a tag when it's being ridden (removing it when it isn't being ridden) and only applying those effects when the entity has the tag by making and animating another animation controller and updating our commands.
<CodeHeader></CodeHeader>
```json
::: code-group
```json [骑乘检测控制器]
"controller.animation.dragon.test_rider":{
"states":{
"default":{
@@ -246,10 +242,12 @@ You might also notice that the entity levitates when you go near it. We can fix
}
}
```
:::
<CodeHeader></CodeHeader>
对应调整命令选择器：
```
::: code-group
```mcfunction
execute @a[rxm=-90,rx=-25] ~~~ effect @e[type=wiki:dragon,r=1,tag=has_rider] levitation 1 6 true
execute @a[rxm=-25,rx=-15] ~~~ effect @e[type=wiki:dragon,r=1,tag=has_rider] levitation 1 3 true
execute @a[rxm=-15,rx=-5] ~~~ effect @e[type=wiki:dragon,r=1,tag=has_rider] levitation 1 2 true
@@ -257,29 +255,27 @@ execute @a[rxm=-5,rx=20] ~~~ effect @e[type=wiki:dragon,r=1,tag=has_rider] levit
execute @a[rxm=20,rx=35] ~~~ effect @e[type=wiki:dragon,r=1,tag=has_rider] slow_falling 1 1 true
execute @a[rxm=35,rx=90] ~~~ effect @e[type=wiki:dragon,r=1,tag=has_rider] clear
```
:::
## Controlling Through Jumping
## 跳跃键控制法
A third method of controlling flying entities uses the player's jump button. The entity rises when the player is holding the jump button and falls when they release their jump button.
通过跳跃键实现升降控制：按住跳跃上升，松开自动下降。
To do this, we need an animation controller attached to the player rather than the entity itself to detect when the player uses their jump button. We also need to disable dismounting when the player presses the jump button.
首先禁用默认跳跃功能：
First, on the entity, disable dismounting and jumping:
<CodeHeader></CodeHeader>
```json
::: code-group
```json [实体组件配置]
"minecraft:horse.jump_strength": {
"value": 0
},
"minecraft:can_power_jump": {}
```
:::
Next, we need an animation controller that causes the entity to levitate when the player uses their jump button and resets the levitation when they release their jump button.
创建响应跳跃输入的动画控制器：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [跳跃键控制器]
"controller.animation.fly_dragon":{
"initial_state":"falling",
"states":{
@@ -306,12 +302,12 @@ Next, we need an animation controller that causes the entity to levitate when th
}
}
```
:::
Now, we need a copy of the player's behavior file, which we will modify slightly. You can find the player's behavior file in the vanilla behavior pack provided by Mojang (found [here](https://aka.ms/behaviorpacktemplate)). Once you have copied the player's behavior file to your own behavior pack, find their `"description"` object and add the animation controller. We also want to ensure that the entity will only respond to the player's jump input when the player is riding it, so we can use a Molang query in the player's behavior to only activate the animation controller when the player is riding.
需修改玩家行为文件（需从[官方模板包](https://aka.ms/behaviorpacktemplate)获取）并添加控制器：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [玩家配置文件]
"description":{
"identifier":"minecraft:player",
"is_spawnable":false,
@@ -328,12 +324,12 @@ Now, we need a copy of the player's behavior file, which we will modify slightly
}
}
```
:::
The entity can now be controlled with the jump key, but there's a bug. If the player dismounts the entity while holding the jump key, it will continue rising. We can fix this with an animation controller on the entity itself that resets the levitation whenever a player dismounts it.
添加离鞍状态复位控制器：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [离鞍复位控制器]
"controller.animation.reset_levitation":{
"initial_state":"no_rider",
"states":{
@@ -357,3 +353,4 @@ The entity can now be controlled with the jump key, but there's a bug. If the pl
}
}
```
:::

108
docs/wiki/3-实体/2-巧思案例/introduction-to-aec.md
View File

@@ -1,78 +1,82 @@
---
title: Introduction to AOE Clouds
category: Tutorials
title: AOE云区域效果介绍
category: 教程
tags:
- intermediate
- 中阶
mentions:
- Sprunkles137
- MedicalJewel105
---
**Area-of-effect clouds**, also known as AOE clouds and `minecraft:area_effect_cloud` internally, are special entities that have many unique properties. Normally these entities are created through throwing lingering potions, but with structures and some NBT editing magic we can manipulate them in very powerful ways for map-making.
# AOE云区域效果介绍
## Overview
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
Area-of-effect clouds have several special features we can take advantage of:
**区域效果云**（Area-of-effect clouds），在内部也被称为AOE云或`minecraft:area_effect_cloud`，是一种具有独特属性的特殊实体。这些实体通常通过投掷滞留药水生成，但借助结构文件和NBT编辑魔法，我们可以在地图制作中以极其强大的方式操控它们。
- As [dummy entities](/entities/dummy-entities), they are highly performant and barely affect framerate, and they are also completely static and have no collision with the world. This makes them perfect for situations around players or where precise positioning is important.
- It does not send the client updates. Once it spawns in, it will visually appear to be frozen in place until it despawns. However, it can still be moved around through commands just fine.
- It can apply any potion effect in highly configurable ways. The duration can be set down to the tick, as well as whether or not the effect is ambient, or displays on the screen, if it emits particles, etc.
- Entities with a runtime identifier of `minecraft:area_effect_cloud` inherit these same properties.
## 概述
## Method 1: Projectile Component
区域效果云具备以下可被利用的特性：
The projectile component supports spawning in area-of-effect clouds on hit. Minecraft uses this to spawn in AOE clouds from lingering potions.
- 作为[虚拟实体](/entities/dummy-entities)，它们在性能表现优异，几乎不影响帧率，且完全静态且不与世界发生碰撞。这使其非常适用于需要围绕玩家或精确定位的场景。
- 不会向客户端发送更新。生成后视觉上会定格在初始位置直至消失，但仍可通过指令自由移动。
- 能以高度可配置的方式施加任何药水效果（精准到游戏刻的持续时间设定，调节环境效果、屏幕提示显示、粒子发射等属性）。
- 具有运行时标识符`minecraft:area_effect_cloud`的实体将继承相同属性。
[Projectiles Documentation](/documentation/projectiles#spawn-aoe-cloud)
## 方法一：投射物组件
## Method 2: NBT Editing
投射物组件支持在命中时生成区域效果云。Minecraft正是通过此机制实现投掷滞留药水生成AOE云。
Another way to spawn in these area-of-effect clouds is through structure files. This grants us finer control over the potion effects the cloud can have. So, our first order of business is getting a means to edit these structures.
[投射物组件文档](/documentation/projectiles#spawn-aoe-cloud)
### NBT Editors
## 方法二：NBT编辑
One of the following NBT editors are recommended:
另一种方式是通过结构文件生成区域效果云。这使我们可以更精细控制云效果属性。首先需要准备合适的NBT编辑工具。
- [NBT Studio](https://github.com/tryashtar/nbt-studio) (a standalone program by tryashtar)
- [NBT Viewer](https://marketplace.visualstudio.com/items?itemName=Misodee.vscode-nbt) (a Visual Studio Code extension by Misode)
### NBT编辑器
### Structure file
推荐使用以下任一NBT编辑器：
For convenience, this article contains a premade structure file you can download and use. Inside is an AOE cloud that exists for the maximum possible time.
- [NBT Studio](https://github.com/tryashtar/nbt-studio)（由tryashtar开发的独立程序）
- [NBT Viewer](https://marketplace.visualstudio.com/items?itemName=Misodee.vscode-nbt)（由Misode开发的VSCode扩展）
<BButton
link="/assets/packs/entities/aec/aec.mcstructure" download
color=blue
>Download MCSTRUCTURE</BButton>
### 结构文件
Refer to this article for editing structure files: [.mcstructure](/nbt/mcstructure)
本文包含预制的结构文件可供下载使用。文件内设置了一个存在时间最大化的AOE云效果。
### NBT Format
::: code-group
```json [点击下载MCSTRUCTURE文件]
```
:::
| Tag | Type | Description |
| --------------------- | ------- | ----------------- |
| Duration | Integer | How long the cloud exists for before expiring, in ticks. |
| DurationOnUse | Integer | How much the duration should change when effects are applied. |
| InitialRadius | Float | The size of this cloud's radius when created. |
| ParticleColor | Integer | The color of the particle effect, in decimal. |
| ParticleId | Integer | The particle effect this cloud emits. 0 emits no particles. |
| PotionId | Short | This cloud's potion effect ID when created. Has no effect. |
| RadiusChangeOnPickup | Float | Unknown. |
| RadiusOnUse | Float | How much the radius should change when effects are applied. |
| RadiusPerTick | Float | How much the radius changes every tick. |
| ReapplicationDelay | Integer | The interval at which effects can be applied, in ticks. |
| mobEffects | List | Describes what potion effects should be applied. |
结构文件编辑指南请参考：[.mcstructure文件解析](/nbt/mcstructure)
Below are the parameters for the `mobEffects` tag.
### NBT数据格式
| Tag | Type | Description |
| ------------------------------- | ------- | --------------- |
| Ambient | Byte | Defines whether this effect's particles should be translucent or not. |
| Amplifier | Byte | The strength of this potion effect. |
| DisplayOnScreenTextureAnimation | Byte | Unknown. |
| Duration | Integer | The amount of time this effect is applied for, in ticks. |
| DurationEasy | Integer | Unknown, seemingly unused. |
| DurationNormal | Integer | Unknown, seemingly unused. |
| DurationHard | Integer | Unknown, seemingly unused. |
| Id | Byte | The potion effect ID for this effect. |
| ShowParticles | Byte | Defines whether this effect's particles should appear or not. |
| 字段 | 类型 | 说明
| --------------------- | ------- | -------------
| Duration | 整型 | 效果云存在总时长（单位：刻）
| DurationOnUse | 整型 | 应用效果后持续时间的增量
| InitialRadius | 浮点型 | 初始生成时的半径
| ParticleColor | 整型 | 粒子颜色（十进制数值）
| ParticleId | 整型 | 发射的粒子类型ID（0表示无粒子）
| PotionId | 短整型 | 药水效果ID（创建时使用，无实质效果）
| RadiusChangeOnPickup | 浮点型 | （未知用途）
| RadiusOnUse | 浮点型 | 应用效果后的半径变化量
| RadiusPerTick | 浮点型 | 每刻半径的变化量
| ReapplicationDelay | 整型 | 两次效果应用的最小间隔（刻）
| mobEffects | 列表 | 实体携带的药水效果配置
以下是`mobEffects`标签的参数说明：
| 字段 | 类型 | 说明
| ------------------------------- | ------- | -------------
| Ambient | 字节 | 效果粒子是否为半透明形态
| Amplifier | 字节 | 效果强度等级（0表示I级）
| DisplayOnScreenTextureAnimation | 字节 | （未知用途）
| Duration | 整型 | 效果持续时间（刻）
| DurationEasy | 整型 | （未知用途，疑似未使用）
| DurationNormal | 整型 | （未知用途，疑似未使用）
| DurationHard | 整型 | （未知用途，疑似未使用）
| Id | 字节 | 药水效果类型ID
| ShowParticles | 字节 | 是否显示效果粒子

64
docs/wiki/3-实体/2-巧思案例/invulnerable-entities.md
View File

@@ -1,6 +1,6 @@
---
title: Invulnerable Entities
category: Tutorials
title: 无敌实体
category: 教程
tags:
- beginner
mentions:
@@ -10,58 +10,62 @@ mentions:
- MedicalJewel105
---
## Using Damage Sensor
# 无敌实体
The best and most flexible way of disabling damage for entities is using the `minecraft:damage_sensor` component. The component allows us to use `filters` to determine which damage sources can damage our entity.
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
The best way to learn about this component is by using the vanilla examples for damage sensor or reading [documentation](https://bedrock.dev/docs/stable/Entities#minecraft:damage_sensor)
## 使用伤害传感器组件
### Completely Invulnerable Entity
禁用实体伤害的最佳且最灵活的方式是使用 `minecraft:damage_sensor` 组件。该组件允许我们通过 `filters` 过滤器来指定哪些伤害源可以作用于实体。
<CodeHeader>BP/entities/entity.json#minecraft:entity/components</CodeHeader>
了解这个组件的最好方法是查阅原版伤害传感器示例或阅读[官方文档](https://bedrock.dev/docs/stable/Entities#minecraft:damage_sensor)
```json
### 完全无敌的实体
::: code-group
```json [BP/entities/entity.json#minecraft:entity/components]
"minecraft:damage_sensor": {
"triggers": {
"cause": "all",
"deals_damage": false
"cause": "all", // 捕捉全部伤害类型
"deals_damage": false // 取消实际伤害效果
}
}
```
:::
### Disable Damage from Player
### 禁止玩家伤害
<CodeHeader>BP/entities/entity.json#minecraft:entity/components</CodeHeader>
```json
::: code-group
```json [BP/entities/entity.json#minecraft:entity/components]
"minecraft:damage_sensor": {
"triggers": {
"on_damage": {
"filters": {
"test": "is_family",
"subject": "other",
"value": "player"
"on_damage": { // 当受到伤害时触发
"filters": { // 过滤器配置
"test": "is_family", // 检测对象类型
"subject": "other", // 检测施加伤害的主体
"value": "player" // 当伤害来源为玩家时生效
}
},
"deals_damage": false
"deals_damage": false // 取消实际伤害效果
}
}
```
:::
## Min Health
## 最低生命值限制
The `min` property in the `minecraft:health` component allows us to make invincible entities that cannot die. This includes when using `/kill @e`. This is not considered a good solution because entities like this are hard to get rid of.
通过 `minecraft:health` 组件中的 `min`（最小值）属性，我们可以创建无法自然死亡的无敌实体（即使使用 `/kill @e` 命令也无法清除）。需要注意的是该方案可能引发后续问题——这类实体会永久驻留世界。
If you choose to use this component, please make sure you have another method for killing the entity. Triggering `minecraft:instant_despawn` from something like an environment sensor, a timer, or an interact is a good solution. You also can call it using `/event`.
如果使用此方案，**请务必配置备用清除机制**。例如通过环境传感器组件、计时器组件或互动组件触发的 `minecraft:instant_despawn` 事件实现清除，也可以通过执行 `/event` 命令手动触发。
<CodeHeader>BP/entities/entity.json#minecraft:entity/components</CodeHeader>
```json
::: code-group
```json [BP/entities/entity.json#minecraft:entity/components]
"minecraft:health": {
"value": 1,
"max": 1,
"min": 1
"value": 1, // 当前生命值
"max": 1, // 最大生命值
"min": 1 // 生命值下限（设置为与max相等将保持血量恒定）
}
```
:::
Note that setting it to 0 breaks some death and spawn animations/effects.
> **技术提示**：将该值设置为0可能会导致部分死亡和重生动画/粒子效果无法正常显示。

41
docs/wiki/3-实体/2-巧思案例/look-at-entity.md
View File

@@ -1,8 +1,8 @@
---
title: Look at Entity
category: Tutorials
title: 看向实体
category: 教程
tags:
- intermediate
- 中级
mentions:
- shanewolf38
- MedicalJewel105
@@ -10,35 +10,42 @@ mentions:
- SmokeyStack
---
The following tutorial provides a resource pack method to detect when the player is looking at an entity. The code below must be placed inside the entity that will be looked at by the player, and will provide a variable `v.look_at_entity` which returns true when the entity is being looked at.
# 看向实体
## variable
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
<CodeHeader>RP/entity/mob.entity.json</CodeHeader>
以下教程提供了一种资源包方法，用于检测玩家何时看向实体。下方代码必须放置在会被玩家注视的实体文件中，并通过变量`v.look_at_entity`返回true值来指示实体当前是否被注视。
```json
## 变量
::: code-group
```json [RP/entity/mob.entity.json]
"pre_animation": [
"v.look_at_entity = Math.abs(Math.abs(q.rotation_to_camera(1) - q.camera_rotation(1)) - 180) < (20 / q.distance_from_camera) && Math.abs(q.rotation_to_camera(0) + q.camera_rotation(0)) < (10 / q.distance_from_camera);"
],
```
:::tip
Because the query `q.rotation_to_camera` is based at the origin of the entity (their feet), the vertical detection range will be based around the bottom of the entity. The code below creates a modified variable for the vertical angle which takes a positional offset into account to allow the vertical detection range to be based around the center of the entity.
:::tip 补充说明
由于查询参数`q.rotation_to_camera`基于实体的原点（脚部位置），垂直检测范围将围绕实体底部进行计算。下方代码通过创建经过位置偏移修正的垂直角度变量，使垂直检测范围能够基于实体中心进行计算。
:::
<CodeHeader>RP/entity/mob.entity.json</CodeHeader>
```json
::: code-group
```json [RP/entity/mob.entity.json]
"pre_animation": [
"v.rotation_to_camera_0 = -Math.atan2(-q.distance_from_camera * Math.sin(q.rotation_to_camera(0)) - 1, q.distance_from_camera * Math.cos(q.rotation_to_camera(0)));",
"v.look_at_entity = Math.abs(Math.abs(q.rotation_to_camera(1) - q.camera_rotation(1)) - 180) < (20 / q.distance_from_camera) && Math.abs(v.rotation_to_camera_0 + q.camera_rotation(0)) < (60 / q.distance_from_camera);"
],
```
## Modifying
## 参数调整
当前代码主要适配标准Minecraft生物规格（1×2方块）。如需适配不同尺寸的实体，需要调整以下参数：
- 数值 `-1` 控制生物中心位置偏移量（负值向上，正值向下）
- 数值 `20` 控制水平角度敏感度
- 数值 `60` 控制垂直角度敏感度
The provided code is very accurate for the standard Minecraft mob size of 1 block wide and 2 blocks tall, but for entities of different sizes the parameters should be changed. The `- 1` controls the positional offset of the center of the mob (- is upward, + is downward), the `20` controls the horizontal angle sensitivity, and the `60` controls the vertical angle sensitivity.
## 实现原理
该变量的工作原理是检测两种旋转角度是否相反：
1. 实体需要转向玩家的旋转角度
2. 玩家需要转向实体的旋转角度
## Explanation
The variable detects when the player is looking at the entity by checking if the rotation angle required for the entity to look at the player is opposite the rotation angle required for the player to look at the entity. The horizontal and vertical angle sensitivity are modified by the distance of the entity from the camera to maintain accuracy.
通过对比水平和垂直方向的角度差值（数值大小通过相机与实体的距离进行动态缩放），即可精确判定注视状态。

173
docs/wiki/3-实体/2-巧思案例/sleeping-entities.md
View File

@@ -1,48 +1,51 @@
---
title: Sleeping Entities
category: Tutorials
title: 睡眠实体
category: 教程
tags:
- intermediate
- 中级
mentions:
- MedicalJewel105
- SirLich
---
This tutorial will explain how to make entity sleep.
# 睡眠实体
## Sleeping in beds
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
This behavior is inspired from villagers.
本文将指导如何为实体添加睡眠功能。
### Features
## 在床上睡眠
- Entity sleeps during the night and wakes up at day time.
- Interaction with entity will wake it up and after a while it goes sleeping again.
- If entity is hurt, it wakes up.
该行为的灵感来源于村民设计。
### Behavior Pack
### 特性
In this section behavior pack components will be discussed.
- 实体在夜晚自动入睡，天亮时苏醒
- 与实体互动可唤醒它，并在一段时间后重新入睡
- 实体受到伤害时会立即清醒
#### Components
### 行为包配置
Let's start with some basic components that you need to add to your entity.
本节将解析行为包所需组件。
<CodeHeader>BP/entities/sleeping_entity.json#components</CodeHeader>
#### 组件
```json
首先在实体组件中添加基础元素：
::: code-group
```json [行为包]
"minecraft:dweller": {
"dwelling_type": "village",
"dweller_role": "inhabitant",
"can_find_poi": true
}
```
:::
Undocumented, needed for entity to be able to sleep.
此组件未经官方文档记载，但实体需要它以实现睡眠功能。
<CodeHeader>BP/entities/sleeping_entity.json#components</CodeHeader>
```json
::: code-group
```json [行为包]
"minecraft:environment_sensor": {
"triggers": [
{
@@ -55,21 +58,20 @@ Undocumented, needed for entity to be able to sleep.
]
}
```
This component is required for entity understand when to sleep.
It runs event if it isn't day time.
:::warning
You need some basic navigation components for your entity be able to move to bed.
:::
#### Component Groups
用于识别何时进入睡眠状态，会在非白天时段触发`sleep`事件。
Now you need some component groups for your entity with some components.
:::warning
注意：实体需具备基础导航组件才能移动到床上。
:::
<CodeHeader>BP/entities/sleeping_entity.json#component_groups</CodeHeader>
#### 组件组
```json
接下来为实体配置复合组件组：
::: code-group
```json [行为包]
"sleeping": {
"minecraft:behavior.sleep": {
"priority": 0,
@@ -118,26 +120,23 @@ Now you need some component groups for your entity with some components.
}
}
```
:::
参数解析：
- `minecraft:behavior.sleep`
定义睡眠行为核心参数，优先级须设为`0`（最高级别）
Determines sleep details, priority needs to be at `0` (the biggest weight).
- `minecraft:damage_sensor``
Add it if you want your entity wake up if it is being attacked.
- `minecraft:damage_sensor`
实现受击苏醒功能
- `minecraft:environment_sensor`
Runs `wake_up` event when it is day time.
白昼时触发`wake_up`事件
- `minecraft:interact`
允许玩家无伤害唤醒实体
This makes player to be able wake up entity without hurting it.
<CodeHeader>BP/entities/sleeping_entity.json#component_groups</CodeHeader>
```json
::: code-group
```json [行为包]
"sleep_timer": {
"minecraft:timer": {
"time": 15,
@@ -147,17 +146,16 @@ This makes player to be able wake up entity without hurting it.
}
}
```
:::
This component group is required for entity to fall asleep again (with some delay) after it was woken up.
此组件组用于设置唤醒后的重新入睡延时。
#### Events
#### 事件配置
Here you will find all events that you need.
I don't really think it needs explanation.
以下事件系统逻辑相对直观：
<CodeHeader>BP/entities/sleeping_entity.json#events</CodeHeader>
```json
::: code-group
```json [行为包]
"sleep": {
"add": {
"component_groups": [
@@ -197,18 +195,18 @@ I don't really think it needs explanation.
}
}
```
:::
### Resource Pack
### 资源包配置
Don't forget that you need to add sleeping animation and controller for it to your entity!
请确保为实体添加睡眠动画和动画控制器！
#### Animation
#### 动画配置
Just copy/paste it.
直接复制以下配置：
<CodeHeader>RP/animations/sleeping_entity.animation.json</CodeHeader>
```json
::: code-group
```json [资源包]
{
"format_version": "1.8.0",
"animations": {
@@ -228,14 +226,14 @@ Just copy/paste it.
}
}
```
:::
#### Animation Controller
#### 动画控制器
Again just copy/paste it if you need.
推荐直接套用此模板：
<CodeHeader>RP/animations_controllers/ac.sleeping_entity.sleep.json</CodeHeader>
```json
::: code-group
```json [资源包]
{
"format_version": "1.10.0",
"animation_controllers": {
@@ -262,36 +260,32 @@ Again just copy/paste it if you need.
}
}
```
:::
Note that you will need to define animation in client entity like this:
注意：需在客户端实体定义中关联动画：`"sleeping": "animation.sleeping_entity.sleep"`
`"sleeping": "animation.sleeping_entity.sleep"`
### Result
### 效果演示
![](/assets/images/tutorials/sleeping-entities/result.png)
## Taking naps
## 小憩系统
This behavior is inspired from foxes.
此行为灵感来源于狐狸设计。
### Features
### 特色功能
- Entity sleeps when feels safe, far from mobs or when the weather is not a thunderstorm.
- Approaching the entity will make it wake up unless it's a trusted or sneaking player, or it's another entity with the family group `sleeping_entity`.
- If entity is hurt, it wakes up.
- 实体在安全环境（远离敌对生物且无雷暴天气）下进入小憩状态
- 仅允许信任的潜行玩家或同族`sleeping_entity`实体靠近时不惊醒
- 受击后自动苏醒
### Behavior Pack
### 行为包配置
In this section behavior pack components will be discussed.
#### 核心组件
#### Components
仅需一个核心组件：
For this behavior you will need only one component:
<CodeHeader>BP/entities/sleeping_entity.json#components</CodeHeader>
```json
::: code-group
```json [行为包]
"minecraft:behavior.nap": {
"priority": 8,
"cooldown_min": 2.0,
@@ -350,22 +344,22 @@ For this behavior you will need only one component:
}
}
```
:::
If you want to also use the trusting mechanic, add:
如需实现信任机制，可附加：
<CodeHeader>BP/entities/sleeping_entity.json#components</CodeHeader>
```json
::: code-group
```json [行为包]
"minecraft:trust": {}
```
:::
### Resource Pack
### 资源包配置
In our resource pack you can run an animation when entity starts to sleep.
可通过动画控制器实现睡眠动画：
<CodeHeader>RP/animations_controllers/ac.sleeping_entity.sleep.json</CodeHeader>
```json
::: code-group
```json [资源包]
{
"format_version": "1.10.0",
"animation_controllers": {
@@ -392,5 +386,6 @@ In our resource pack you can run an animation when entity starts to sleep.
}
}
```
::>
The last thing, you will have to create and register a sleeping animation for you entity. If you don't know how to do it check out the [BlockBench page](/guide/blockbench.html#animating).
最后需要为实体创建并注册睡眠动画，若存在制作难题可参考[BlockBench动画教程](/guide/blockbench.html#animating)。

70
docs/wiki/3-实体/2-巧思案例/solid-entities.md
View File

@@ -1,9 +1,9 @@
---
title: Solid Entities
category: Tutorials
title: 实体碰撞体
category: 教程
tags:
- recipe
- intermediate
- 配方指南
- 中级
mentions:
- SirLich
- Joelant05
@@ -13,78 +13,82 @@ mentions:
- ThomasOrs
---
Solid entities are entities that the player can bump into, step on, or otherwise physically interact with without passing through. Entities like this have many uses, such as emulating blocks.
# 实体碰撞体
This page will discuss some of the ways that solid entities can be created.
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
Not all techniques are ideal for all scenarios. Experiment, and figure out what works best for you.
实体碰撞体是指玩家能够碰撞、踩踏或与之发生物理互动，而不会穿透的实体。这类实体有多种用途，例如模拟方块效果。
## Runtime Identifiers
本页将探讨几种创建实体碰撞体的方法。
[Runtime identifiers](/entities/runtime-identifier) can be used to achieve solid entities, but currently only 2, each with a specific shape, and their own side effects. Neither collision shapes are possible to change or scale.
并非所有技术都适用于所有场景。建议多加实验，找到最适合您需求的方案。
### Boat
## 运行时标识符
<CodeHeader>BP/entities/entity_name.json</CodeHeader>
通过[运行时标识符](/entities/runtime-identifier)可以实现实体碰撞效果。但目前仅支持两种预设形态，每种形态具有特定的碰撞箱及副作用。且两种模型的碰撞形状均不可调节或缩放。
```json
### 船型实体
::: code-group
```json [BP/entities/entity_name.json]
{
"format_version": "1.16.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:solid_entity",
"runtime_identifier": "minecraft:boat"
. . .
// 此处省略其他配置...
}
}
}
```
:::
- Boat-shaped solid collision
- Certain other boat-like effects
- 采用船形的实体碰撞箱
- 具备部分船只特有交互特性
### Shulker
### 潜影贝型实体
<CodeHeader>BP/entities/entity_name.json</CodeHeader>
```json
::: code-group
```json [BP/entities/entity_name.json]
{
"format_version": "1.16.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:solid_entity",
"runtime_identifier": "minecraft:shulker"
. . .
// 此处省略其他配置...
}
}
}
```
:::
- 1x1 block sized solid collision.
- Sticks to block grid.
- Teleports randomly when supporting block removed.
- 1×1方块尺寸的实体碰撞箱
- 固定于方块网格
- 当支撑方块被移除时会随机瞬移
## minecraft:is_stackable
## minecraft:is_stackable 组件
Add `minecraft:is_stackable` to your entity you want to be treated as being solid.
**Note:** This requires editing `player.json` if you wish the entity to be solid for the player.
通过给实体添加`minecraft:is_stackable`组件可使其具有实体碰撞属性。
**注意：** 如果希望实体对玩家而言具有碰撞，需要修改`player.json`文件。
`"minecraft:is_stackable": {}`
You will also need to add `minecraft:push_through` and set its `value` parameter to 1.
同时还需添加`minecraft:push_through`组件，并将其`value`参数设为1：
`"minecraft:push_through": 1`
(they should both go in `components`)
（这两个组件都应置于`components`项下）
## Faking it with blocks
## 模拟方块效果
In some scenarios, it's probably better to `/setblock` or `/fill` to place barrier blocks, either statically or dynamically. There needs to be both a way of placing the barriers, and removing them.
某些情况下更适合使用`/setblock`或`/fill`命令静态或动态放置屏障方块。需配套提供屏障的放置与清除机制：
`/fill ~ ~ ~ ~ ~1 ~ barrier 0 replace air`
Places barriers in a 1x1x2 area.
在1×1×2区域生成屏障方块。
`/fill ~1 ~1 ~1 ~-1 ~-1 ~-1 air 0 replace barrier`
Removes barriers within a 3x3x3 area.
清除3×3×3范围内的屏障方块。
These [commands](/animation-controllers/entity-commands) will have to be triggering at a constant rate, for consistency. They can either be triggered through entity components, or animation controllers.
为保证效果连贯性，这些[动画控制器实体指令](/animation-controllers/entity-commands)需要保持持续激活状态。可通过实体组件或动画控制器实现持续触发。

289
docs/wiki/3-实体/2-巧思案例/timers.md
View File

@@ -1,8 +1,8 @@
---
title: Entity Timers
category: Tutorials
title: 实体计时器
category: 教程
tags:
- intermediate
- 中级
mentions:
- SirLich
- Joelant05
@@ -13,32 +13,36 @@ mentions:
- zheaEvyline
---
Time-based interactions are extremely useful tools for map making. This article hopes to provide an extensive list which details the many ways which timers can be made. For convenience, this page will be split up into two main sections: component-based timers and animation-based timers. Each has their own advantages and disadvantages, which will be outlined in their respective sections.
You might also find useful [Scoreboard Timers](/commands/scoreboard-timers).
# 实体计时器
## Component-based timers
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
Component-based timers are done inside the entity.json file of the behavior pack. They have the distinct advantage of persisting upon the entity being reloaded, but are limited by the number of timing components (duplicate components replace each other, which means defining multiple timers using the `minecraft:timer` component isn't possible).
基于时间的交互是地图制作的超实用工具。本文旨在提供一份详尽的指南，详解多种创建计时器的方法。为方便阅读，本页将分为两大部分：组件计时器和动画计时器。每种方式都有其独特优劣，我们将在对应章节详细探讨。
### minecraft:timer
你可能也会对[计分板计时器](/commands/scoreboard-timers)感兴趣。
This is the simplest but most effective component for triggering events after an elapsed amount of time. The component [minecraft:timer](https://bedrock.dev/docs/1.14.0.0/1.14.30.2/Entities#minecraft:timer) provides three main ways in which the amount of time before the event can be defined:
## 基于组件的计时器
- Exact timing: an exact amount of time after which the event will fire is defined (e.g. 3.4 seconds)
- Random interval: an interval is defined in which the event will fire at a random time inside that interval (e.g. between 3 to 5 seconds)
- Weighted random choice: a number of times are defined and assigned weights, one of which will be chosen for the event to fire (e.g. a 20% chance for the event to fire at 5 seconds, and an 80% chance to fire at 20 seconds)
组件计时器通过行为包的`entity.json`文件实现。其最大优点是实体重载时仍能保持计时状态，但受限于可用的计时组件数量（重复组件会互相覆盖，意味着无法通过`minecraft:timer`组件创建多个独立计时器）。
In the vanilla Behavior Pack, this component is used in all kinds of circumstances. For example:
### minecraft:timer组件
- The dolphin can only spend 20 seconds on land before it dries out
- Bees will perish between 10 and 60 seconds after stinging
- The wandering trader will only stay for either 2400 or 3600 seconds
这是最简单却最高效的延时触发事件组件。[minecraft:timer](https://bedrock.dev/docs/1.14.0.0/1.14.30.2/Entities#minecraft:timer)提供三种主要时间设定方式：
A simple example which triggers an event after 5.6 seconds:
- **精确计时**：固定时间后触发事件（例如3.4秒）
- **随机区间**：在指定时间区间内随机触发（例如3到5秒之间）
- **权重随机选择**：定义多组时间选项配比权重，随机选择其中一个时间触发（例如20%概率5秒触发，80%概率20秒触发）
<CodeHeader></CodeHeader>
在官方行为包中，该组件被广泛应用。例如：
```json
- 海豚在陆地超过20秒后会脱水
- 蜜蜂在蜇人后10-60秒随机死亡
- 流浪商人停留时间为2400秒或3600秒
基础示例（5.6秒后触发事件）：
::: code-group
```json [实体组件]
"minecraft:timer": {
"time": 5.6,
"time_down_event": {
@@ -46,31 +50,19 @@ A simple example which triggers an event after 5.6 seconds:
}
}
```
:::
A more complex example which triggers an event after a randomized amount of delay using weighted values:
进阶示例（使用权重系统随机延时触发）：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [实体组件]
"minecraft:timer": {
"looping": false, //true will fires event after every execution, false will fire event only once.
"looping": false, //true表示循环执行，false表示仅执行一次
"random_time_choices": [
{
"weight": 25,
"value": 0.5 //Half a second of delay
},
{
"weight": 25,
"value": 10 //Ten seconds of delay
},
{
"weight": 25,
"value": 30 //Thirty seconds of delay
},
{
"weight": 25,
"value": 120 //2 minutes of delay
}
{"weight":25, "value":0.5}, //0.5秒延时
{"weight":25, "value":10}, //10秒延时
{"weight":25, "value":30}, //30秒延时
{"weight":25, "value":120} //2分钟延时
],
"time_down_event": {
"event": "wiki:event",
@@ -78,69 +70,59 @@ A more complex example which triggers an event after a randomized amount of dela
}
}
```
:::
A particularly useful way to handle time events is using a single, looping `minecraft:timer` component and processing the events on each tick (or however often you decide to fire the timer). This is done by using the `randomize` parameter in events, where a weight may be used determine how often other events will be run. This can get you a lot of extra mileage out of a single timer component.
高效利用技巧：通过循环触发`minecraft:timer`，配合事件中的`randomize`参数实现多样效果。这里通过权重控制事件触发频率：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [事件配置]
"wiki:do_event": {
"randomize": [
{
"weight": 1,
"add": {
"component_groups": [
"wiki:my_event"
]
}
"weight": 1, //1/56概率触发稀有事件
"add": {"component_groups":["wiki:my_event"]}
},
{
"weight": 5,
"add": {
"component_groups": [
"wiki:my_more_frequent_event"
]
}
"weight": 5, //5/56概率触发常见事件
"add": {"component_groups":["wiki:my_more_frequent_event"]}
},
{
"weight": 50 //Fires nothing
"weight": 50 //50/56概率无事件触发
}
]
}
```
:::
### minecraft:environment_sensor
### minecraft:environment_sensor组件
Another component ([minecraft:environment_sensor](https://bedrock.dev/docs/stable/Entities#minecraft:environment_sensor)) which can be very useful for time-based events is `minecraft:environment_sensor`. Pairing this sensor with the `hourly_clock_time` or `clock_time` filters can be used to trigger events based off in-game time.
当结合`hourly_clock_time`或`clock_time`筛选器时，[minecraft:environment_sensor](https://bedrock.dev/docs/stable/Entities#minecraft:environment_sensor)可用于游戏内时间触发事件。
Here is an example which is used to fire an event 800 ticks after the start of the day (valid range is 0 to 24000):
示例（每日开始800tick后触发事件）：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [实体组件]
"minecraft:environment_sensor": {
"triggers": [
{
"filters": {
"test": "hourly_clock_time",
"operator": "=",
"value": 800
},
"event": "wiki:my_daily_event"
}
]
"triggers": [{
"filters": {
"test": "hourly_clock_time",
"operator": "=",
"value": 800
},
"event": "wiki:my_daily_event"
}]
}
```
:::
### minecraft:ageable
### minecraft:ageable组件
If this component ([minecraft:ageable](https://bedrock.dev/docs/stable/Entities#minecraft:ageable)) is not being used in the entity's behavior for a different purpose, it can be useful as an additional timer. It's important to note that it requires the `minecraft:is_baby` component to be defined in order to function.
当行为包未占用[miinecraft:ageable](https://bedrock.dev/docs/stable/Entities#minecraft:ageable)时，可配合`minecraft:is_baby`组件实现计时功能。
Here is an example which fires an event after four seconds:
示例（4秒后触发事件）：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [实体组件]
"minecraft:is_baby": {},
"minecraft:ageable": {
"duration": 4,
@@ -150,171 +132,138 @@ Here is an example which fires an event after four seconds:
}
}
```
:::
### Other dummy-timers:
### 其他计时组件思路
Taking a peak at the docs suggest there are other components which can also can be used for timing. Essentially, you are looking for any component with a "time down event" or a "duration".
查阅文档可发现更多具有"time_down_event"或"duration"参数的潜在组件，例如：
Non-exhaustive list of promising examples:
- `minecraft:angry`（需要攻击目标，时间限定整数）
- `minecraft.behavior.hide`
- `minecraft:behavior.celebrate`
- `minecraft:angry` (requires the entity to have a target, time must be an integer)
- `minecraft.behavior.hide`
- `minecraft:behavior.celebrate`
## 基于动画的计时器
## Animation-based timers
行为包动画是实现定时事件的强力工具。其优势在于理论上可创造无限计时器，但存在重载实体时重置的局限（玩家退出世界或区块卸载后重新加载会重置计时器）。
Behavior pack animations are an extremely powerful tool for triggering time-based events. They have the distinct advantage of providing an "infinite" amount of timers, but are restarted upon an entity being reloaded (leaving and rejoining the world or the chunk containing the entity unloading will cause the timer to restart when the entity reloads).
动画在行为包中的运作方式与资源包不同，建议通过官方文档或wiki其他页面了解基本机制。
Animations function differently in behavior packs than in resource packs. If you are unfamiliar with how they operate, it is recommended to learn more about them by checking out the official documentation or the other pages on this wiki.
### 基础动画计时
### Simple timers
通过动画控制器或直接执行时间线指令，可以实现精确时序触发：
By triggering animations from an animation controller or directly from the scripts section, you can execute specific events, commands, or molang expressions in a timed-sequence, called a timeline.
You can set up timelines like this:
<CodeHeader></CodeHeader>
```json
::: code-group
```json [动画定义]
{
"format_version": "1.8.0",
"animations": {
"animation.command.example_timeline": {
"timeline": {
"0.0": "/say this will trigger instantly",
"3.0": "/say this will trigger after 3 seconds"
"0.0": "/say 立即触发",
"3.0": "/say 3秒后触发"
},
"animation_length": 3.1
},
"animation.command.example_timeline_2": {
"timeline": {
"100": "/say this will trigger after 100 seconds",
"100": "/say 100秒后触发",
"0.0": [
"/say you can trigger multiple events at once",
"/say by using timelines."
"/say 同时触发多个指令",
"/say 通过时间线组实现"
],
"55.55": "/say this will trigger after 55.55 seconds."
"55.55": "/say 55.55秒后触发"
},
"animation_length": 100.1
}
}
}
```
:::
### Random interval
### 随机间隔实现
A very useful feature of the timer component is its ability to define a random interval in which the event will be triggered. This functionality can be replicated using animations and a controller. Below is an example of an animation triggered by adding the `minecraft:is_sheared` component to an entity which randomly fires an event between 2 to 7 seconds after activation. Animation and controller version 1.10.0.
通过动画控制器模拟`minecraft:timer`的随机区间功能。示例：实体被剪毛后2-7秒随机触发事件。
<CodeHeader></CodeHeader>
```json
::: code-group
```json [动画控制器]
"controller.animation.shanewolf.random_interval": {
"initial_state": "inactive",
"states": {
"inactive": {
"transitions": [
{
"active": "q.is_sheared"
}
]
"transitions": [{"active": "q.is_sheared"}]
},
"active": {
"on_entry": [
"v.random_interval = math.random(2, 7);",
"/say random interval started"
],
"animations": [
"wiki:animate_interval"
],
"transitions": [
{
"inactive": "q.anim_time >= v.random_interval"
}
"/say 随机计时开始"
],
"animations": ["wiki:animate_interval"],
"transitions": [{
"inactive": "q.anim_time >= v.random_interval"
}],
"on_exit": [
"@s wiki:stop_random_interval",
"/say random interval finished"
"/say 随机计时结束"
]
}
}
}
```
:::
<CodeHeader></CodeHeader>
```json
::: code-group
```json [动画定义]
"animation.shanewolf.random_interval": {
"animation_length": 100
}
```
:::
Explanation: Upon entry into the state beginning the animation, a variable is given a random value between 2 and 7. The animation finishes when the current animation time is greater than or equal to the value of this v.
实现逻辑：进入激活状态时生成2-7秒随机数变量，动画播放时间超过变量值时退出状态。
**Notes**:
- The animation length can be set to any value greater than the maximum end of the time range (100 is used as a general template)
- math.random(a, b) is used to trigger an event in the range [a, b]
- math.floor(math.random(a, b.99)) may be used to end the timer at integer values (0.99 must be added to b)
- Any events or commands to run when the animation is finished are put inside on_exit
注意事项：
- 动画总时长需大于最大可能值
- 使用`math.floor(math.random(a, b.99))`可生成整数结果
- 收尾指令写入on_exit事件
### Weighted random choice
### 权重选择实现
Another useful feature of the timer component is its ability to trigger events at a time determined by a weighted list of values. This functionality can also be replicated using animations and a controller. Below is an example of an animation triggered by adding the `minecraft:is_charged` component to an entity which randomly fires an event at either 2, 5, or 9 seconds with weights of 30, 60, and 10, respectively. Animation and controller version 1.10.0.
通过动画控制器模拟权重时间选择功能。示例：带电实体30%概率2秒、60%概率5秒、10%概率9秒触发事件。
<CodeHeader></CodeHeader>
```json
::: code-group
```json [动画控制器]
"controller.animation.shanewolf.random_choices": {
"initial_state": "inactive",
"states": {
"inactive": {
"transitions": [
{
"active": "q.is_powered"
}
]
"transitions": [{"active": "q.is_powered"}]
},
"active": {
"on_entry": [
"v.random_choices = math.random(0, 100);",
"/say random interval started"
],
"animations": [
"wiki:animate_choices"
"/say 随机选择开始"
],
"animations": ["wiki:animate_choices"],
"transitions": [
{
"inactive": "q.anim_time >= 2.0 && v.random_choices < 30"
},
{
"inactive": "q.anim_time >= 5.0 && v.random_choices < 90"
},
{
"inactive": "q.anim_time >= 9.0 && v.random_choices <= 100"
}
{"inactive": "q.anim_time >= 2.0 && v.random_choices < 30"},
{"inactive": "q.anim_time >= 5.0 && v.random_choices < 90"},
{"inactive": "q.anim_time >= 9.0 && v.random_choices <= 100"}
],
"on_exit": [
"@s wiki:stop_random_choices",
"/say random choices finished"
"/say 随机选择结束"
]
}
}
}
```
:::
<CodeHeader></CodeHeader>
实现逻辑：生成0-100随机数变量，通过多个状态切换条件实现权重分段检查。
```json
"animation.shanewolf.random_choices": {
"animation_length": 100
}
```
注意事项：
- 时间段需从小到大排列
- 通过权重累加值划分概率区间
- 按规范处理收尾事件
Explanation: Upon entry into the state beginning the animation, a variable is given a random value between 0 and 100 (sum of the weights). The transitions are laid out with the list of values ordered from the smallest time to the largest time. This is done so multiple && operators are not required in the latter transitions to define the variable's range (the query for the smallest times return true first and have their weights checked before the others--flipping 2 and 5 would result in 2 mistakenly having a weight of 90 instead of 30). The animation finishes when the current animation time is greater than or equal to a time in the list and the value of the random variable falls within that time's defined weight range.
**Notes**:
- The animation length can be set to any value greater than the maximum end of the time range (100 is used as a general template)
- For this particular format to work, order the list of valid times from smallest to largest
- To assign a weight to a time in the list, add the weight to the value the randomized variable must be less than in the list's previous entry (e.g. 5 seconds has a weight of 90 - 30 = 60)
- Any events or commands to run when the animation is finished are put inside on_exit
Hopefully this spread some light on the subject of handling time in Minecraft Bedrock! As shown above, there are many possible ways it can be done, each with their own pros and cons. If you have any other useful methods for creating time-based events, please [contribute to the wiki](/contribute)!
希望本指南能帮助你更好地掌握基岩版的时间管理技巧！如果你有其他巧妙的时间事件实现方法，欢迎[参与wiki编辑](/contribute)！

206
docs/wiki/3-实体/2-巧思案例/village-mechanic.md
View File

@@ -1,6 +1,6 @@
---
title: Village Mechanic
category: Tutorials
title: 村庄机制
category: 教程
mentions:
- AeroForta
- MedicalJewel105
@@ -11,15 +11,18 @@ mentions:
- ThomasOrs
---
This article is for anyone who wants to try imitate the village mechanic for their entities
# 村庄机制
## Navigation Behavior
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
First let's start with some basic navigation behavior.
本文适用于想要为自定义实体实现村庄机制的开发者
<CodeHeader>BP/entities/custom_villager.json#components</CodeHeader>
## 导航行为
```json
首先从基本导航行为开始。
::: code-group
```json [BP/entities/custom_villager.json#components]
"minecraft:preferred_path":{
"max_fall_blocks":1,
"jump_cost":5,
@@ -48,12 +51,12 @@ First let's start with some basic navigation behavior.
]
}
```
:::
Allows entity to do random walk.
允许实体进行随机移动。
<CodeHeader>BP/entities/custom_villager.json#components</CodeHeader>
```json
::: code-group
```json [BP/entities/custom_villager.json#components]
"minecraft:behavior.random_stroll":{
"priority":9,
"speed_multiplier":0.55,
@@ -61,83 +64,83 @@ Allows entity to do random walk.
"y_dist":5
}
```
:::
Make entity return to inside dwelling bound, in this case inside a village border. Requiring minecraft:dweller component that will be explained below.
使实体返回居所范围（在此案例中即村庄边界）。需要下文将解释的`minecraft:dweller`组件。
<CodeHeader>BP/entities/custom_villager.json#components</CodeHeader>
```json
::: code-group
```json [BP/entities/custom_villager.json#components]
"minecraft:behavior.move_towards_dwelling_restriction": {
"priority": 4,
"speed_multiplier": 1.0
}
```
:::
Makes entity navigate around a village by creating a path to patrol. Used by Iron Golem.
通过创建巡逻路径让实体在村庄周围移动。铁傀儡使用的机制。
<CodeHeader>BP/entities/custom_villager.json#components</CodeHeader>
```json
::: code-group
```json [BP/entities/custom_villager.json#components]
"minecraft:behavior.move_through_village": {
"priority": 3,
"speed_multiplier": 0.6,
"only_at_night": true
}
```
:::
Allows entity to enter a building and also take shelter when raining. Needs open door capabilities.
允许实体进入建筑物并在下雨时寻找庇护所。需要开门能力。
<CodeHeader>BP/entities/custom_villager.json#components</CodeHeader>
```json
::: code-group
```json [BP/entities/custom_villager.json#components]
"minecraft:behavior.move_indoors":{
"priority":5
}
```
:::
Makes entity stay indoors while sun is down.
使实体在日落时留在室内。
<CodeHeader>BP/entities/custom_villager.json#components</CodeHeader>
```json
::: code-group
```json [BP/entities/custom_villager.json#components]
"minecraft:behavior.restrict_open_door":{
"priority": 5
}
```
:::
Use in pair with:
需搭配使用：
<CodeHeader>BP/entities/custom_villager.json#components</CodeHeader>
```json
::: code-group
```json [BP/entities/custom_villager.json#components]
"minecraft:annotation.open_door":{
"priority": 5
}
```
:::
<CodeHeader>BP/entities/custom_villager.json#components</CodeHeader>
```json
::: code-group
```json [BP/entities/custom_villager.json#components]
"minecraft:navigation.walk":{
"can_pass_doors":true,
"can_open_doors":true
}
```
:::
<CodeHeader>BP/entities/custom_villager.json#components</CodeHeader>
```json
::: code-group
```json [BP/entities/custom_villager.json#components]
"minecraft:behavior.open_door":{
"priority":6,
"close_door_after":true
}
```
:::
## Main Behavior
## 核心行为
<CodeHeader>BP/entities/custom_villager.json#components</CodeHeader>
```json
::: code-group
```json [BP/entities/custom_villager.json#components]
"minecraft:dweller": {
"dwelling_type": "village",
"dweller_role": "inhabitant",
@@ -149,36 +152,34 @@ Use in pair with:
"first_founding_reward": 5
}
```
:::
- `dweller_role: inhabitant`
Allows entity claim a bed and bell.
`minecraft:behavior.sleep` needed.
- `preferred_profession: farmer`
Optional for `minecraft:behavior.work`
- `can_find_poi`
Add it so entity is able to find point of interest.
Known POI types:
- `dweller_role: inhabitant`\
允许实体认领床和钟，需搭配`minecraft:behavior.sleep`。
- `preferred_profession: farmer`\
为`minecraft:behavior.work`的可选参数
- `can_find_poi`\
启用后实体可寻找兴趣点。已知兴趣点类型：
```
bed
jobsite
meeting_area
bed // 床
jobsite // 工作站点
meeting_area // 聚集点
```
- `can_migrate`
Defines if entity can migrate from one village to another or not.
- `can_migrate`\
定义实体是否能在不同村庄间迁移
### Sleep
### 睡眠行为
You can find out how to make your entity sleep [here](/entities/sleeping-entities).
可参考[睡眠实体指南](/entities/sleeping-entities)实现实体睡眠
### Work
### 工作行为
Requires "dweller_role" set to be "inhabitant" also if "preferred_profession" doesn't exist the entity will try to move to the closest any job site.
需要设置"dweller_role"为"inhabitant"，若未设置"preferred_profession"则实体将移动到最近的工作站点。
<CodeHeader></CodeHeader>
```json
::: code-group
```json [空值]
"minecraft:behavior.work": {
"priority": 4,
"active_time": 250,
@@ -194,12 +195,12 @@ Requires "dweller_role" set to be "inhabitant" also if "preferred_profession" do
}
}
```
:::
### 社交行为
### Gathering
Allows the entity to gather.
Requires "dweller_role" set to be "inhabitant".
允许实体进行社交活动。
需要设置"dweller_role"为"inhabitant"。
```json
"minecraft:behavior.mingle": {
@@ -212,16 +213,14 @@ Requires "dweller_role" set to be "inhabitant".
}
```
## 日程系统
### Scheduler
现在将所有机制整合到"minecraft:scheduler"中。
首先创建简单配置。
将工作行为放入组件组：
Now you know everything about needed mechanic, let's try to put all of this together in "minecraft:scheduler"
First let's do something simple.
Put work behavior in component group work like this:
<CodeHeader></CodeHeader>
```json
::: code-group
```json [空值]
"component_groups":{
"work_schedule":{
"minecraft:behavior.work":{
@@ -251,12 +250,12 @@ Put work behavior in component group work like this:
}
}
```
:::
Next, make your entity work.
配置工作日程：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [空值]
"minecraft:scheduler":{
"min_delay_secs":0,
"max_delay_secs":10,
@@ -267,12 +266,12 @@ Next, make your entity work.
{
"test":"hourly_clock_time",
"operator":">=",
"value":0 //Morning
"value":0 // 早晨
},
{
"test":"hourly_clock_time",
"operator":"<",
"value":12000 //Evening
"value":12000 // 傍晚
}
]
},
@@ -298,12 +297,12 @@ Next, make your entity work.
]
}
```
:::
The events section looks something like this:
事件部分配置示例：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [空值]
"events":{
"work":{
"remove":{
@@ -331,27 +330,28 @@ The events section looks something like this:
}
}
```
:::
Open your world, spawn entity then put a bed and you should see green particle.
进入游戏生成实体后放置床，应可见绿色粒子效果。
## Other Behavior
## 其他行为
All of this is usable by custom entities:
- `minecraft:behavior.move_to_village`
Used by Pillager this may keep the entity to stay in the village.
- `minecraft:behavior.stroll_towards_village`
Used by fox to search a village and go there.
- `minecraft:behavior.inspect_bookshelf`
Used by librarian villager allows an entity to look at and inspect a bookshelf.
- `minecraft:behavior.explore_outskirts`
Allows entity to explore beyond the bounds of village (use schedule and component group to keep the entity return to the village).
- `minecraft:behavior.defend_village_target`
Use this on melee attack. Ranged attack can accidentally shoot any entity with inhabitant dwelling role.
以下行为可供自定义实体使用：
- `minecraft:behavior.move_to_village`\
劫掠者使用该机制来留在村庄
- `minecraft:behavior.stroll_towards_village`\
狐狸使用该机制寻找并前往村庄
- `minecraft:behavior.inspect_bookshelf`\
管理员村民用于查看书架
- `minecraft:behavior.explore_outskirts`\
允许实体在村庄外探索（需搭配日程系统组件组保证返回）
- `minecraft:behavior.defend_village_target`\
用于近战攻击。远程攻击可能误伤具有"inhabitant" role的实体
All of this can be used by custom entities and have relation to villager or village:
| Behavior | Uses | Note |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `minecraft:behavior.defend_village_target` | Allows entity to attack other entity that hurt the entity who had "dweller_role": "inhabitant". | Recommended to use only on entities with melee attack. |
| `minecraft:behavior.hide` | Used by villager to hide and stay at defined POI. | Currently, there is no documentation for the POI type that's why I recommend not to change `"poi_type": "bed"`. |
| `minecraft:behavior.move_to_village` | Used by Illager and also witch. Allows entity to travel to a random x,y,z coordinate in a village. | - |
| `"minecraft:behavior.nap"` | Used by Fox to take a nap. | Similar with sleep but offers more flexibility also has built-in wake up system by detecting specific entity. |
可用行为对照表：
| 行为名称 | 用途 | 备注 |
| ----------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `minecraft:behavior.defend_village_target` | 允许实体攻击伤害村民的敌人 | 建议仅用于近战攻击型实体 |
| `minecraft:behavior.hide` | 村民用于在特定POI隐藏停留 | 当前POI类型文档不完整，建议保持`"poi_type": "bed"` |
| `minecraft:behavior.move_to_village` | 劫掠者和女巫用于在村庄范围内随机移动 | - |
| `minecraft:behavior.nap` | 狐狸用于小憩 | 类似睡眠但更灵活，内置感知特定实体自动唤醒系统 |

4
docs/wiki/3-实体/3-文档/vanilla-usage-components.md
View File

@@ -1,11 +1,11 @@
---
title: Vanilla 可用 Components
title: 所有可用 Components
category: Documentation
mentions:
- MedicalJewel105
---
# Vanilla 可用 Components
# 所有可用 Components
<!--@include: @/wiki/bedrock-wiki-mirror.md-->

4
docs/wiki/3-实体/3-文档/vanilla-usage-spawn-rules.md
View File

@@ -1,11 +1,11 @@
---
title: Vanilla 可用生成规则（Spawn Rules）
title: 所有可用生成规则（Spawn Rules）
category: Documentation
mentions:
- MedicalJewel105
---
# Vanilla 可用生成规则（Spawn Rules）
# 所有可用生成规则（Spawn Rules）
<!--@include: @/wiki/bedrock-wiki-mirror.md-->

4
docs/wiki/3-实体/3-文档/vuc-full.md
View File

@@ -1,12 +1,12 @@
---
title: Vanilla 可用 Components - 完整
title: 所有可用 Components - 完整
category: Documentation
mentions:
- MedicalJewel105
hidden: true
---
# Vanilla 可用 Components - 完整
# 所有可用 Components - 完整
<!--@include: @/wiki/bedrock-wiki-mirror.md-->

4
docs/wiki/3-实体/3-文档/vusr-full.md
View File

@@ -1,12 +1,12 @@
---
title: Vanilla 可用 Spawn Rules - 完整
title: 所有可用 Spawn Rules - 完整
category: Documentation
mentions:
- MedicalJewel105
hidden: true
---
# Vanilla 可用 Spawn Rules - 完整
# 所有可用 Spawn Rules - 完整
<!--@include: @/wiki/bedrock-wiki-mirror.md-->

374
docs/wiki/4-Json-UI/1-基础/json-ui-intro.md
View File

@@ -306,11 +306,13 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
```
:::
当更改时，派生元素的任何属性都将被完全覆盖。
## 数据绑定
通过 `bindings` 实现数据源与元素的动态关联。
绑定机制用于将硬编码值与界面元素关联，并在处理元素时使用这些值。以下是一个使用硬编码文本的标签示例：
### 简单绑定
`text`属性值设定为`#hardtext`。通过`bindings`配置，我们可以获取硬编码变量`#hardtext`的值，使`text`属性能够正确调用。这种配置直接将`#hardtext`的值赋给`text`属性。
::: code-group
```json [vanilla/ui/example_file.json]
@@ -328,18 +330,18 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
```
:::
### 重定向绑定
另一种常见的配置形式如下：
::: code-group
```json [vanilla/ui/example_file.json]
{
"label": {
"type": "label",
"text": "#display_text",
"text": "#text",
"bindings": [
{
"binding_name": "#source_data",
"binding_name_override": "#display_text"
"binding_name": "#hardtext",
"binding_name_override": "#text"
}
]
}
@@ -347,18 +349,27 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
```
:::
### 跨元素绑定
此时，`#hardtext`的值会被赋给`#text`绑定属性，进而传递给`text`属性。
这种机制在`visible`（可见性）和`enabled`（启用状态）属性中尤为常见。以下是一个组合示例：
::: code-group
```json
{
"status_panel": {
"send_button": {
"bindings": [
{
"binding_type": "view",
"source_control_name": "my_toggle",
"source_property_name": "#state",
"target_property_name": "#visible"
"binding_name": "#using_touch",
"binding_name_override": "#visible"
}
]
},
"play_button": {
"bindings": [
{
"binding_name": "#play_button_enabled",
"binding_name_override": "#enabled"
}
]
}
@@ -366,117 +377,70 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
```
:::
## 条件渲染
此处的`#using_touch`和`#play_button_enabled`存储布尔值。当使用触控设备时，`#using_touch`为`true`，否则为`false`。`#play_button_enabled`用于「添加外部服务器」界面，当所有文本字段（服务器名称、IP地址和端口号）均有内容时才会设为`true`。<br>
因此，`#using_touch`的值会覆盖`#visible`绑定属性（该属性通常通过`property_bag`设置，等同于直接设置`visible`属性），同理`#play_button_enabled`会覆盖`#enabled`的值。
通过变量和绑定实现动态显示控制。
### 变量条件
当需要根据开关状态显示特定面板时，需使用另一种绑定结构。这种配置需要指定数据源元素、源属性及目标属性：
::: code-group
```json [vanilla/ui/hud_screen.json]
```json
{
"hud_actionbar_text/actionbar_message": {
"$atext": "$actionbar_text",
"visible": "(not ($atext = 'hello world'))"
}
}
```
:::
### 工厂条件
::: code-group
```json [vanilla/ui/hud_screen.json]
{
"conditional_image": {
"type": "image",
"texture": "textures/ui/Black",
"$atext": "$actionbar_text",
"visible": "($atext = 'show_image')"
"panel": {
...
"bindings": [
{
"binding_type": "view",
"source_control_name": "my_toggle", // 源元素名称
"source_property_name": "#toggle_state", // 需要获取的开关状态属性
"target_property_name": "#visible" // 待覆盖的目标属性
}
]
},
"image_factory": {
"type": "panel",
"factory": {
"name": "hud_actionbar_text_factory",
"control_ids": {
"hud_actionbar_text": "conditional_image@hud.conditional_image"
}
}
"my_toggle": {
...
}
}
```
:::
通过结合操作符系统，可实现复杂的条件逻辑判断，为界面交互提供灵活的控制能力。
当开关被勾选时，`#toggle_state`会变为`1`或`true`，从而将元素的`visible`属性设为可见。取消勾选时，该值变为`0`或`false`，再次覆盖`visible`属性值。
::: code-group
```json [vanilla/ui/hud_screen.json]
```
## 条件性渲染
在标准属性体系下，通过屏幕显示状态控制基岩版UI系统具有挑战性。然而变量（variables）和绑定（bindings）在JSON UI中具有特殊地位，因为它们承载着来自基岩引擎的实时数据。通过巧妙的UI技巧组合，开发者可以完全控制UI元素的渲染条件。这些方法分为两大类：基于变量的条件渲染和基于绑定的条件渲染。
:::warning ⚠️ 注意
本示例适用于国际版的受限制的 JSON UI 系统（客户端无法实现脚本控制）<br>
对中国版来说，不需要这种复杂的黑科技实现HUD元素的可见性控制。<br>
但是也能因此学习到数据绑定的使用方法，何尝不是一种收获呢？
:::
### 使用绑定的条件渲染
### 变量条件渲染
根据上文提到的操作栏示例，你可能会认为标题也使用变量。但实际情况并非如此。标题使用绑定（bindings）来获取数据，如下所示。
变量可用于实现条件性UI渲染。UI变量是指前缀带`$`的特殊属性，例如`hud_screen.json`中的`$actionbar_text`就承载着引擎数据。观察`hud_actionbar_text`控件可知，该变量用于显示动作栏文本。
::: code-group
```json [vanilla/ui/hud_screen.json]
{
...
"hud_title_text": {
"type": "stack_panel",
"orientation": "vertical", // 垂直排列
"offset": [ 0, -19 ], // 位置偏移
"layer": 1, // 渲染层级
"alpha": "@hud.anim_title_text_alpha_in", // 透明度动画
"propagate_alpha": true, // 透明度继承
"controls": [ // 子控件集合
"hud_actionbar_text": {
"type": "image",
"size": [ "100%c + 12px", "100%c + 5px" ],
"offset": [ 0, "50%-68px" ],
"texture": "textures/ui/hud_tip_text_background",
"alpha": "@hud.anim_actionbar_text_background_alpha_out",
"controls": [
{
"title_frame": {
"type": "panel", // 面板类型
"size": [ "100%", "100%cm" ], // 尺寸设置
"controls": [
{
"title_background": {
"type": "image", // 图像类型
"size": [ "100%sm + 30px", "100%sm + 6px" ], // 动态尺寸计算
"texture": "textures/ui/hud_tip_text_background", // 纹理路径
"alpha": "@hud.anim_title_background_alpha_in" // 背景透明度动画
}
},
{
"title": {
"type": "label", // 文本标签类型
"anchor_from": "top_middle", // 锚点起始位置
"anchor_to": "top_middle", // 锚点目标位置
"color": "$title_command_text_color", // 文字颜色变量
"text": "#text", // 文本内容绑定
"layer": 1, // 渲染层级
"localize": false, // 关闭本地化
"font_size": "extra_large", // 超大字号
"variables": [ // 条件变量组
{
"requires": "(not $title_shadow)", // 无阴影条件
"$show_shadow": false // 关闭阴影显示
},
{
"requires": "$title_shadow", // 启用阴影条件
"$show_shadow": true // 启用阴影显示
}
],
"shadow": "$show_shadow", // 阴影状态绑定
"text_alignment": "center", // 文本居中
"offset": [ 0, 6 ], // 位置微调
"bindings": [ // 数据绑定组
{
"binding_name": "#hud_title_text_string", // 原始绑定名
"binding_name_override": "#text", // 覆盖目标属性
"binding_type": "global" // 全局绑定类型
}
]
}
}
]
"actionbar_message": {
"type": "label",
"anchor_from": "center",
"anchor_to": "center",
"color": "$tool_tip_text",
"layer": 1,
"text": "$actionbar_text",
"localize": false,
"alpha": "@hud.anim_actionbar_text_alpha_out"
}
}
]
@@ -486,7 +450,100 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
```
:::
我们需要在文本组件中添加另一个绑定对象来控制可见性。注意`#visible`属性会通过绑定直接控制元素可见性。以下示例将不会渲染"hello world"标题，但会显示其他所有标题。可在游戏中输入`/title @s title hello world`观察效果。
通过`visible`属性可实现基于引擎变量的条件渲染。以下示例复制了`$actionbar_text`变量以便进行修改和比较（原始变量无法直接操作）。新建的`$atext`变量用于控制`visible`属性，其逻辑是"当动作栏文本不等于`hello world`时显示文本标签"。
::: code-group
```json [vanilla/ui/hud_screen.json]
{
...
"hud_actionbar_text": {
"type": "image",
"size": ["100%c + 12px", "100%c + 5px"],
"offset": [0, "50%-68px"],
"texture": "textures/ui/hud_tip_text_background",
"alpha": "@hud.anim_actionbar_text_background_alpha_out",
"controls": [
{
"actionbar_message": {
"type": "label",
"anchor_from": "center",
"anchor_to": "center",
"color": "$tool_tip_text",
"layer": 1,
"text": "$actionbar_text",
"localize": false,
"alpha": "@hud.anim_actionbar_text_alpha_out",
// 当动作栏文本等于"hello world"时忽略该文本标签
"$atext": "$actionbar_text",
"visible": "(非 ($atext = 'hello world'))"
}
}
]
}
...
}
```
:::
将此JSON转换为资源包使用的非侵入式UI文件应如下所示：
::: code-group
```json [vanilla/ui/hud_screen.json]
{
"hud_actionbar_text/actionbar_message": {
"$atext": "$actionbar_text",
"visible": "(非 ($atext = 'hello world'))"
}
}
```
:::
在启用资源包的世界中执行`/title @s actionbar hello world`时，动作栏将不会显示信息。其他动作栏指令仍可正常显示。若需要同时隐藏文本背景，可移除`/actionbar_message`节点。由于背景元素`hud_actionbar_text`被隐藏时，其子元素也会连带隐藏。
下面展示更复杂的变量条件渲染示例。此处需要使用动作栏工厂（actionbar factory）。工厂是元素生成器，其中`hud_actionbar_text_factory`等具有硬编码属性。该工厂在每次执行动作栏指令时重置其`control_id`内的元素，并传递`$actionbar_text`等特殊变量，这些数据只能通过工厂获取。
::: code-group
```json [vanilla/ui/hud_screen.json]
{
"black_conditional_image": {
"type": "image",
"texture": "textures/ui/Black",
"size": [16, 16],
"layer": 10,
"$atext": "$actionbar_text",
"visible": "($atext = 'hello world')"
},
"black_conditional_image_factory": {
"type": "panel",
"factory": {
"name": "hud_actionbar_text_factory",
"control_ids": {
"hud_actionbar_text": "black_conditional_image@hud.black_conditional_image"
}
}
},
"root_panel": {
"modifications": [
{
"array_name": "controls",
"operation": "insert_front",
"value": {
"black_conditional_image_factory@hud.black_conditional_image_factory": {}
}
}
]
}
}
```
:::
当动作栏文本等于`hello world`时，此示例会在HUD界面显示16x16黑色方块。开发者可为图像添加动画增强表现力。变量条件渲染不仅限于图像和文本，任何UI对象类型均可应用。结合动作栏文本的UI代码可实现高度定制化（至少在`hud_screen.json`中）。`visible`属性支持UI运算符，提供更精细的控制。任何承载引擎数据的变量都支持变量条件渲染。
### 绑定条件渲染
观察标题系统（title）时，可能误以为其使用变量系统。实际上标题系统采用绑定机制获取数据，如下所示：
::: code-group
```json [vanilla/ui/hud_screen.json]
@@ -525,7 +582,76 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
"font_size": "extra_large",
"variables": [
{
"requires": "(not $title_shadow)",
"requires": "(非 $title_shadow)",
"$show_shadow": false
},
{
"requires": "$title_shadow",
"$show_shadow": true
}
],
"shadow": "$show_shadow",
"text_alignment": "center",
"offset": [ 0, 6 ],
"bindings": [
{
"binding_name": "#hud_title_text_string",
"binding_name_override": "#text",
"binding_type": "global"
}
]
}
}
]
}
}
]
}
...
}
```
:::
通过添加绑定对象控制可见性。`#visible`属性直接反映元素的可见状态。以下示例将隐藏`hello world`标题文本，其他文本正常显示。游戏中可执行`/title @s title hello world`验证效果。
::: code-group
```json [vanilla/ui/hud_screen.json]
{
...
"hud_title_text": {
"type": "stack_panel",
"orientation": "vertical",
"offset": [ 0, -19 ],
"layer": 1,
"alpha": "@hud.anim_title_text_alpha_in",
"propagate_alpha": true,
"controls": [
{
"title_frame": {
"type": "panel",
"size": [ "100%", "100%cm" ],
"controls": [
{
"title_background": {
"type": "image",
"size": [ "100%sm + 30px", "100%sm + 6px" ],
"texture": "textures/ui/hud_tip_text_background",
"alpha": "@hud.anim_title_background_alpha_in"
}
},
{
"title": {
"type": "label",
"anchor_from": "top_middle",
"anchor_to": "top_middle",
"color": "$title_command_text_color",
"text": "#text",
"layer": 1,
"localize": false,
"font_size": "extra_large",
"variables": [
{
"requires": "(非 $title_shadow)",
"$show_shadow": false
},
{
@@ -543,9 +669,9 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
"binding_type": "global"
},
{
"binding_type": "view", // 将此设为视图绑定
"source_property_name": "(not (#text = 'hello world'))", // 当标题文本不等于"hello world"时触发
"target_property_name": "#visible" // 根据条件覆盖可见性属性
"binding_type": "view", // 转换为视图绑定
"source_property_name": "(非 (#text = 'hello world'))", // 检测标题文本是否不等于"hello world"
"target_property_name": "#visible" // 根据检测结果覆盖可见性属性
}
]
}
@@ -560,7 +686,7 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
```
:::
在资源包中使用非侵入式UI文件修改时，应保持如下格式：
转换为资源包文件时应如下配置：
::: code-group
```json [RP/ui/hud_screen.json]
@@ -568,11 +694,11 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
"hud_title_text/title_frame/title": {
"modifications": [
{
"array_name": "bindings", // 目标数组名
"operation": "insert_back", // 末尾插入操作
"value": { // 新增绑定对象
"array_name": "bindings",
"operation": "insert_back",
"value": {
"binding_type": "view",
"source_property_name": "(not (#text = 'hello world'))",
"source_property_name": "(非 (#text = 'hello world'))",
"target_property_name": "#visible"
}
}
@@ -582,24 +708,24 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
```
:::
下面是一个更复杂的条件渲染示例。16x16的黑色图片仅在标题文本等于"hello world"时显示。虽然在此案例中不需要使用标题工厂（title factory），但如需使用UI动画则建议采用。
下方是更复杂的绑定条件渲染示例。当标题文本等于`hello world`时显示16x16黑色图像。虽然不强制要求使用标题工厂，但若涉及UI动画则推荐使用。
::: code-group
```json [RP/ui/hud_screen.json]
{
"black_conditional_image": {
"type": "image",
"texture": "textures/ui/Black", // 黑色纹理
"size": [16, 16], // 固定尺寸
"layer": 10, // 较高渲染层级
"texture": "textures/ui/Black",
"size": [16, 16],
"layer": 10,
"bindings": [
{
"binding_name": "#hud_title_text_string" // 标题文本绑定
"binding_name": "#hud_title_text_string"
},
{
"binding_type": "view",
"source_property_name": "(#hud_title_text_string = 'hello world')", // 条件判断
"target_property_name": "#visible" // 可见性控制
"source_property_name": "(#hud_title_text_string = 'hello world')",
"target_property_name": "#visible"
}
]
},
@@ -607,9 +733,9 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
"black_conditional_image_factory": {
"type": "panel",
"factory": {
"name": "hud_title_text_factory", // 使用标题工厂
"name": "hud_title_text_factory",
"control_ids": {
"hud_title_text": "black_conditional_image@hud.black_conditional_image" // 控件ID映射
"hud_title_text": "black_conditional_image@hud.black_conditional_image"
}
}
},
@@ -617,10 +743,10 @@ UI 元素是 JSON UI 的基本组成单元，每个命名空间内的元素名
"root_panel": {
"modifications": [
{
"array_name": "controls", // 根面板控件数组
"operation": "insert_front", // 前置插入
"array_name": "controls",
"operation": "insert_front",
"value": {
"black_conditional_image_factory@hud.black_conditional_image_factory": {} // 工厂实例
"black_conditional_image_factory@hud.black_conditional_image_factory": {}
}
}
]

5
docs/wiki/4-Json-UI/2-巧思案例/add-hud-elements.md
View File

@@ -12,6 +12,11 @@ mentions:
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
:::warning ⚠️ 注意
本教程仅适用于国际版的受限制的 JSON UI 系统（客户端无法实现脚本控制）<br>
中国版无需使用此黑科技实现HUD元素新增。
:::
在本教程中，你将学习如何向HUD界面添加元素。
## 概述

4
docs/wiki/4-Json-UI/2-巧思案例/aseprite-animations.md
View File

@@ -1,5 +1,5 @@
---
title: Aseprite动画
title: 序列帧动画
category: 教程
mentions:
- TheDataLioness
@@ -9,7 +9,7 @@ mentions:
- stirante
---
# Aseprite动画
# 序列帧动画（Aseprite）
<!--@include: @/wiki/bedrock-wiki-mirror.md-->

37
docs/wiki/4-Json-UI/2-巧思案例/preserve-title-texts.md
View File

@@ -1,5 +1,5 @@
---
title: 保留标题文本
title: Title传递HUD元素更新
category: 教程分类
tags:
- 中级
@@ -8,26 +8,31 @@ mentions:
- SmokeyStack
---
# 保留标题文本
# 通过 Title 传递 HUD 元素更新
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
在本教程中，您将学习如何保存绑定数据并根据含有特定字符串的标题更新界面元素。
:::warning ⚠️ 注意
本教程仅适用于国际版的受限制的 JSON UI 系统（客户端无法实现脚本控制）<br>
中国版无需使用此黑科技实现HUD元素的更新。
:::
在本教程中，您将学习如何保存绑定数据并根据含有特定字符串的 Title 更新界面元素。
## 概述
标题是向UI系统传递数据的常用方法。当标题包含特定字符串时才更新相关数据元素，而忽略所有不含该字符串的标题数据非常有用。尽管本教程以标题为例，但该方法适用于所有通过绑定传递的数据（如副标题、玩家记分板名称等）。
Title 是向UI系统传递数据的常用方法。当 Title 包含特定字符串时才更新相关数据元素，而忽略所有不含该字符串的 Title 数据非常有用。尽管本教程以 Title 为例，但该方法适用于所有通过绑定传递的数据（如副 Title 、玩家记分板名称等）。
要保存特定字符串，我们需要组合使用 `visibility_changed` 绑定更新条件和 `source_control_name`，从而仅在包含特定字符串时更新绑定，并将该绑定传递给另一个元素。
## 标题指令
## Title 指令
以下代码创建了一个标签元素，当将其添加到根面板时，可以在屏幕显示包含字符串"update"的标题（显示文本中会移除"update"部分）。后续传入的标题信息只有包含"update"时才会更新显示文本。
以下代码创建了一个标签元素，当将其添加到根面板时，可以在屏幕显示包含字符串"update"的 Title （显示文本中会移除"update"部分）。后续传入的 Title 信息只有包含"update"时才会更新显示文本。
::: code-group
```json [RP/ui/hud_screen.json]
"preserved_title_display": {
"$update_string": "update", // 标题必须包含此字符串才触发元素更新
"$update_string": "update", // Title 必须包含此字符串才触发元素更新
"type": "label",
"text": "#text",
"controls": [
@@ -37,14 +42,14 @@ mentions:
"size": [ 0, 0 ],
"bindings": [
{
"binding_name": "#hud_title_text_string" // 读取当前标题字符串
"binding_name": "#hud_title_text_string" // 读取当前 Title 字符串
},
{
"binding_name": "#hud_title_text_string",
"binding_name_override": "#preserved_text", // 元素可见性变化时更新#preserved_text
"binding_condition": "visibility_changed"
},
// 当包含更新字符的标题传入后，元素会短暂可见后立即隐藏
// 当包含更新字符的 Title 传入后，元素会短暂可见后立即隐藏
{
"binding_type": "view",
"source_property_name": "(not (#hud_title_text_string = #preserved_text) and not ((#hud_title_text_string - $update_string) = #hud_title_text_string))",
@@ -66,13 +71,13 @@ mentions:
},
```
变量 `$update_string` 定义了触发元素更新的标题必须包含的特定字符串。子元素 `data_control` 用于在标题包含更新字符串时存储标题文本。`data_control` 必须是要传递保留文本元素的子级或同级元素，因为其可见性变化会触发文本保存。该元素的三个绑定分别实现：
1. 首绑定：持续追踪当前标题文本
2. 次绑定：在元素可见性变化时将当前标题保存至 `#preserved_text`
3. 末绑定：当传入含更新字符串的标题时短暂显示元素后立即隐藏
变量 `$update_string` 定义了触发元素更新的 Title 必须包含的特定字符串。子元素 `data_control` 用于在 Title 包含更新字符串时存储 Title 文本。`data_control` 必须是要传递保留文本元素的子级或同级元素，因为其可见性变化会触发文本保存。该元素的三个绑定分别实现：
1. 首绑定：持续追踪当前 Title 文本
2. 次绑定：在元素可见性变化时将当前 Title 保存至 `#preserved_text`
3. 末绑定：当传入含更新字符串的 Title 时短暂显示元素后立即隐藏
在 `data_control` 元素的第三个绑定中，需同时满足两个条件才可见：
1. `not (#hud_title_text_string = #preserved_text)` - 当前标题与保存标题不一致时成立
2. `not ((#hud_title_text_string - $update_string)` - 当前标题含有更新字符串时成立
1. `not (#hud_title_text_string = #preserved_text)` - 当前 Title 与保存 Title 不一致时成立
2. `not ((#hud_title_text_string - $update_string)` - 当前 Title 含有更新字符串时成立
当含有更新字符串且与已存文本不同的标题传入时，两条件同时触发，元素更新数据后立即重新隐藏自身。
当含有更新字符串且与已存文本不同的 Title 传入时，两条件同时触发，元素更新数据后立即重新隐藏自身。

78
docs/wiki/4-Json-UI/3-文档/json-ui-documentation.md
View File

@@ -1,5 +1,5 @@
---
title: JSON UI Documentation
title: JSON UI 完整文档
category: Documentation
nav_order: 1
mentions:
@@ -23,43 +23,55 @@ mentions:
- Gotemba912
---
# JSON UI Documentation
# JSON UI 完整文档
## UI Elements
## UI元素
### Element Types
### 元素类型
| Name | Description | Allowed Properties |
| ---------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| panel | A container, like `<div>` in HTML | [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| stack_panel | Similar to `panel` but stacks its children depending on `orientation` property value | [Stack Panel](/json-ui/json-ui-documentation#stack-panel) <br> [Collection](/json-ui/json-ui-documentation#collection) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| collection_panel | Similar to `stack_panel`, but does not have the `orientation` property | [Collection](/json-ui/json-ui-documentation#collection) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| grid | Grid of elements | [Grid](/json-ui/json-ui-documentation#grid) <br> [Collection](/json-ui/json-ui-documentation#collection) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| label | Text element | [Text](/json-ui/json-ui-documentation#text) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| image | Sprite element. Draws a texture. | [Sprite](/json-ui/json-ui-documentation#sprite) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| input_panel | A `panel` that accepts input | [Input](/json-ui/json-ui-documentation#input) <br> [Focus](/json-ui/json-ui-documentation#focus) <br> [Sound](/json-ui/json-ui-documentation#sound) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| button | A button and it can have 4 states (default, hover, pressed and locked) | [Button](/json-ui/json-ui-documentation#button) <br> [Input](/json-ui/json-ui-documentation#input) <br> [Focus](/json-ui/json-ui-documentation#focus) <br> [Sound](/json-ui/json-ui-documentation#sound) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| toggle | A toggle and it has 2 states (checked or unchecked). Each state has a hover and locked variant | [Toggle](/json-ui/json-ui-documentation#toggle) <br> [Input](/json-ui/json-ui-documentation#input) <br> [Focus](/json-ui/json-ui-documentation#focus) <br> [Sound](/json-ui/json-ui-documentation#sound) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| dropdown | A toggle for dropdown purposes | [Dropdown](/json-ui/json-ui-documentation#dropdown) <br> [Toggle](/json-ui/json-ui-documentation#toggle) <br> [Input](/json-ui/json-ui-documentation#input) <br> [Focus](/json-ui/json-ui-documentation#focus) <br> [Sound](/json-ui/json-ui-documentation#sound) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| slider | Range input element | [Slider](/json-ui/json-ui-documentation#slider) <br> [Input](/json-ui/json-ui-documentation#input) <br> [Focus](/json-ui/json-ui-documentation#focus) <br> [Sound](/json-ui/json-ui-documentation#sound) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| slider_box | The slider button that you use to change the slider value | [Slider Box](/json-ui/json-ui-documentation#slider-box) <br> [Input](/json-ui/json-ui-documentation#input) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| edit_box | Text field element. By default it's single-lined | [Text Edit](/json-ui/json-ui-documentation#text-edit) <br> [Button](/json-ui/json-ui-documentation#button) <br> [Input](/json-ui/json-ui-documentation#input) <br> [Focus](/json-ui/json-ui-documentation#focus) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| scroll_view | Creates a scrolling panel element | [Scroll View](/json-ui/json-ui-documentation#scroll-view) <br> [Input](/json-ui/json-ui-documentation#input) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| scrollbar_track | The scrollbar track | [Input](/json-ui/json-ui-documentation#input) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) |
| scrollbar_box | The scrollbar "thumb"/button. The draggable scrolling handle. By default is oriented vertically | [Input](/json-ui/json-ui-documentation#input) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) |
| factory | A element generator | [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) |
| screen | Screen element | [Screen](/json-ui/json-ui-documentation#screen) [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| custom | Special renderer element that is created in the code because it's too complex for JSON UI | [Custom Render](/json-ui/json-ui-documentation#custom-render) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| selection_wheel | | [Selection Wheel](/json-ui/json-ui-documentation#selection-wheel) <br> [Input](/json-ui/json-ui-documentation#input) <br> [Focus](/json-ui/json-ui-documentation#focus) <br> [Sound](/json-ui/json-ui-documentation#sound) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| 名称 | 描述 | 允许的属性 |
| ------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| panel | 容器元素，类似HTML中的`<div>` | [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| stack_panel | 类似`panel`，但会根据`orientation`属性值自动堆叠子元素 | [堆叠面板](/json-ui/json-ui-documentation#stack-panel) <br> [集合](/json-ui/json-ui-documentation#collection) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| collection_panel | 类似`stack_panel`，但没有`orientation`属性 | [集合](/json-ui/json-ui-documentation#collection) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| grid | 网格布局元素 | [网格](/json-ui/json-ui-documentation#grid) <br> [集合](/json-ui/json-ui-documentation#collection) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| label | 文本元素 | [文本](/json-ui/json-ui-documentation#text) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| image | 图像元素，用于绘制纹理 | [精灵](/json-ui/json-ui-documentation#sprite) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| input_panel | 可接收输入的面板 | [输入](/json-ui/json-ui-documentation#input) <br> [焦点](/json-ui/json-ui-documentation#focus) <br> [音效](/json-ui/json-ui-documentation#sound) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| button | 按钮元素，支持四种状态（默认、悬停、按下、锁定） | [按钮](/json-ui/json-ui-documentation#button) <br> [输入](/json-ui/json-ui-documentation#input) <br> [焦点](/json-ui/json-ui-documentation#focus) <br> [音效](/json-ui/json-ui-documentation#sound) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| toggle | 开关元素，包含两种状态（选中/未选中），每种状态有悬停和锁定变体 | [开关](/json-ui/json-ui-documentation#toggle) <br> [输入](/json-ui/json-ui-documentation#input) <br> [焦点](/json-ui/json-ui-documentation#focus) <br> [音效](/json-ui/json-ui-documentation#sound) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| dropdown | 下拉菜单开关 | [下拉菜单](/json-ui/json-ui-documentation#dropdown) <br> [开关](/json-ui/json-ui-documentation#toggle) <br> [输入](/json-ui/json-ui-documentation#input) <br> [焦点](/json-ui/json-ui-documentation#focus) <br> [音效](/json-ui/json-ui-documentation#sound) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| slider | 范围输入元素 | [滑块](/json-ui/json-ui-documentation#slider) <br> [输入](/json-ui/json-ui-documentation#input) <br> [焦点](/json-ui/json-ui-documentation#focus) <br> [音效](/json-ui/json-ui-documentation#sound) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| slider_box | 用于调整滑块值的拖动按钮 | [滑块按钮](/json-ui/json-ui-documentation#slider-box) <br> [输入](/json-ui/json-ui-documentation#input) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| edit_box | 文本输入框（默认单行） | [文本编辑](/json-ui/json-ui-documentation#text-edit) <br> [按钮](/json-ui/json-ui-documentation#button) <br> [输入](/json-ui/json-ui-documentation#input) <br> [焦点](/json-ui/json-ui-documentation#focus) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| scroll_view | 创建可滚动面板 | [滚动视图](/json-ui/json-ui-documentation#scroll-view) <br> [输入](/json-ui/json-ui-documentation#input) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| scrollbar_track | 滚动条轨道 | [输入](/json-ui/json-ui-documentation#input) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) |
| scrollbar_box | 滚动条"滑块"（可拖动的滚动手柄，默认垂直方向） | [输入](/json-ui/json-ui-documentation#input) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) |
| factory | 元素生成器 | [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) |
| screen | 屏幕元素 | [屏幕](/json-ui/json-ui-documentation#screen) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| custom | 需通过代码创建的复杂渲染元素 | [自定义渲染](/json-ui/json-ui-documentation#custom-render) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| selection_wheel | 选择轮盘 | [选择轮盘](/json-ui/json-ui-documentation#selection-wheel) <br> [输入](/json-ui/json-ui-documentation#input) <br> [焦点](/json-ui/json-ui-documentation#focus) <br> [音效](/json-ui/json-ui-documentation#sound) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
#### Legacy Element Types (No longer work)
#### 遗留元素类型（已失效）
| Name | Description | Allowed Properties |
| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| tab | The way tabs were made before the addition of toggles | [Tab](/json-ui/json-ui-documentation#tab-legacy) <br> [Button](/json-ui/json-ui-documentation#button) <br> [Input](/json-ui/json-ui-documentation#input) <br> [Focus](/json-ui/json-ui-documentation#focus) <br> [Sound](/json-ui/json-ui-documentation#sound) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| carousel_label | | [Carousel Text](/json-ui/json-ui-documentation#carousel-text-legacy) <br> [Text](/json-ui/json-ui-documentation#text) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| grid_item | A `panel` but specifically to be an item/child of a grid | [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| scrollbar | | [Input](/json-ui/json-ui-documentation#input) <br> [Focus](/json-ui/json-ui-documentation#focus) <br> [Control](/json-ui/json-ui-documentation#control) <br> [Layout](/json-ui/json-ui-documentation#layout) <br> [Data Binding](/json-ui/json-ui-documentation#data-binding) |
| 名称 | 描述 | 允许的属性 |
| ---------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tab | 在引入toggle之前创建标签页的方式 | [标签页（旧版）](/json-ui/json-ui-documentation#tab-legacy) <br> [按钮](/json-ui/json-ui-documentation#button) <br> [输入](/json-ui/json-ui-documentation#input) <br> [焦点](/json-ui/json-ui-documentation#focus) <br> [音效](/json-ui/json-ui-documentation#sound) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| carousel_label | 轮播文本元素 | [轮播文本（旧版）](/json-ui/json-ui-documentation#carousel-text-legacy) <br> [文本](/json-ui/json-ui-documentation#text) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| grid_item | 专门作为网格子元素的容器 | [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
| scrollbar | 旧版滚动条 | [输入](/json-ui/json-ui-documentation#input) <br> [焦点](/json-ui/json-ui-documentation#focus) <br> [控件](/json-ui/json-ui-documentation#control) <br> [布局](/json-ui/json-ui-documentation#layout) <br> [数据绑定](/json-ui/json-ui-documentation#data-binding) |
::: code-group
```json [示例]
// 代码块注释示例
{
"panel": {
"type": "stack_panel",
"orientation": "vertical"
}
}
```
:::
## Properties

173
docs/wiki/commands/block-entities.md Normal file
View File

@@ -0,0 +1,173 @@
---
title: MBE - Max's Block Entity
category: Techniques
mention:
- BedrockCommands
- zheaEvyline
tags:
- system
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
This method, developed by Reddit user [u/Maxed_Out10](https://www.reddit.com/user/Maxed_Out10/) allows you to create near-perfect entity replications of any Minecraft block using armour stands and some sequential `/playanimation` commands.
To preserve credits to the creator, the community termed this method as "Max's Block Entity" or MBE for short.
### Points to Note
1. This method uses 1 armour stand per block entity. Therefore, too many armour stands (like any entity) can contribute to server lag.
2. Players will still be able to pass through them as well as interact with them if not restricted.
3. While the block entity may appear in one spot, it's actual hitbox will have a slight offset.
## Video Demonstration
<YouTubeEmbed
id="kb8rz9ItE_M"
/>
## Setup
*To be typed in chat:*
1. `/summon armor_stand Grumm`
- It is necessary to name it 'Grumm' to avoid inverted block textures.
2. `/execute as @e [type= armor_stand, name=Grumm, c=1] at @s run tp @s ~~~ 260`
- This will align the MBE to the normal Minecraft block grid.
ㅤ
:::tip
- Crouch & right-click (on mcpe: long press) the armor stand 6 times to place it in Pose 7
- Doing this negates the need to use the 2nd command in the system.
- **Only use this if you wish to reduce one command from the system.**
:::
## System
> Note: adding a delay of 100-200 ticks is recommended.
<CodeHeader>mcfunction</CodeHeader>
```yaml
/effect @e [type= armor_stand, name=Grumm] invisibility 999999 1 true
/playanimation @e [type= armor_stand, name=Grumm] animation.armor_stand.entertain_pose null 0 "0" align.arms
/playanimation @e [type= armor_stand, name=Grumm] animation.player.move.arms.zombie null 0 "0" size.mini_block
/playanimation @e [type= armor_stand, name=Grumm] animation.ghast.scale null 0 "0" size.full_block
/playanimation @e [type= armor_stand, name=Grumm] animation.fireworks_rocket.move null 0 "0" align.full_block
/execute as @e [type= armor_stand, name=Grumm] at @s run tp ~~~
```
![commandBlockChain6](/assets/images/commands/commandBlockChain/6.png)
### Purpose Of Each Command
1. Hides the armour stand body.
2. Automatically sets the armour stand pose to 7 for arms alignment. Skip this command you prefer to do it manually.
3. __Required command__. Increases size to present as mini-block.
4. *Optional command.* Increases size to present as full-block.
5. *Optional command.* Aligns the full-block size MBE properly.
- Skip 4 & 5 if you do not need full-block size MBE.
6. Locks in place to prevent fall in case block underneath is removed.
## Rotations & Alignments
> Note: These rotation commands are to be executed only once through a command block.
<Spoiler title="Full MBE">
```yaml
# Face North
/tp @e [type=armor_stand, name=Grumm, c=1] ~-1.1245 ~0.2260 ~-0.097 81
# Face South
/tp @e [type=armor_stand, name=Grumm, c=1] ~1.1245 ~0.2260 ~0.097 260
# Face East
/tp @e [type=armor_stand, name=Grumm, c=1] ~0.097 ~0.2260 ~-1.1245 171
# Face West
/tp @e [type=armor_stand, name=Grumm, c=1] ~-0.097 ~0.2260 ~1.1245 350
```
</Spoiler>
<Spoiler title="Mini MBE">
```yaml
# Face North
/tp @e [type=armor_stand, name=Grumm, c=1] ~-0.417~-0.5 ~-0.035 81
# Face South
/tp @e [type=armor_stand, name=Grumm, c=1] ~0.417 ~-0.5 ~0.035 260
# Face East
/tp @e [type=armor_stand, name=Grumm, c=1] ~0.035 ~-0.5 ~-0.417 171
# Face West
/tp @e [type=armor_stand, name=Grumm, c=1] ~-0.035 ~-0.5 ~0.417 350
```
</Spoiler>
<Spoiler title="Stair MBE">
```yaml
# Face North
/tp @e [type=armor_stand, name=Grumm, c=1] ~-0.097 ~0.2325 ~1.1245 350
# Face South
/tp @e [type=armor_stand, name=Grumm, c=1] ~0.097 ~0.2325 ~-1.1245 171
# Face East
/tp @e [type=armor_stand, name=Grumm, c=1] ~-1.1245 ~0.2325 ~-0.097 81
# Face West
/tp @e [type=armor_stand, name=Grumm, c=1] ~1.1245 ~0.2325 ~0.097 260
```
</Spoiler>
<Spoiler title="Bottom Slab MBE">
```yaml
# Face North
/tp @e [type=armor_stand, name=Grumm, c=1] ~-0.097 ~0.2325 ~1.1245 350
# Face South
/tp @e [type=armor_stand, name=Grumm, c=1] ~0.097 ~0.2325 ~-1.1245 171
# Face East
/tp @e [type=armor_stand, name=Grumm, c=1] ~-1.1245 ~0.2325 ~-0.097 81
# Face West
/tp @e [type=armor_stand, name=Grumm, c=1] ~1.1245 ~0.2325 ~0.097 260
```
</Spoiler>
<Spoiler title="Top Slab MBE">
```yaml
# Face North
/tp @e [type=armor_stand, name=Grumm, c=1] ~-1.1245 ~0.484 ~-0.097 81
# Face South
/tp @e [type=armor_stand, name=Grumm, c=1] ~1.1245 ~0.484 ~0.097 260
# Face East
/tp @e [type=armor_stand, name=Grumm, c=1] ~0.097 ~0.484 ~-1.1245 171
# Face West
/tp @e [type=armor_stand, name=Grumm, c=1] ~-0.097 ~0.484 ~1.1245 350
```
</Spoiler>
## Saving & Loading MBE
1. To save run:
- `/execute as @e [type=armor_stand, name=Grumm, c=1] at @s run structure save MBE ~~~ ~~~`
2. To load run:
- `/structure load MBE <coordinates>`
> Note: structure name `MBE` can be changed to your preference.

118
docs/wiki/commands/block-states.md Normal file
View File

@@ -0,0 +1,118 @@
---
title: Block States
category: General
mentions:
- BedrockCommands
- zheaEvyline
- SmokeyStack
- ThomasOrs
tags:
- info
---
## Introduction
[Sourced by Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
Block States or Block Properties are additional data that defines how the block appears or behaves. Such as the direction it is facing, it's color, it's variant, whether it is powered or unpowered and so on.
This is used in a multitude of commands such as `/clone`, `/execute`, `/fill`, `/setblock` and `/testforblock`
In Bedrock Edition we used Aux values (also known as Metadata) to define a block. However; as of 1.19.70 and beyond this is no longer supported and have been fully replaced with Block States instead.
<CodeHeader>example</CodeHeader>
```yaml
#Aux Value Example:
/setblock ~ ~ ~ wool 1
#It's Block State equivalent:
/setblock ~ ~ ~ wool ["color"="orange"]
```
- Any command block using aux values will continue to function as it is however block states will need to be adopted when updating them.
- Similarly any commands using aux values in behaviour or function packs with `min_engine_version` 1.19.63 or below will also continue to function however block states must be adopted if the `min_engine_version` is updated to 1.19.70 or above.
## Block State Examples & Syntax
<CodeHeader>Examples</CodeHeader>
```yaml
/setblock ~ ~ ~ wool ["color"="white"]
/setblock ~ ~ ~ wheat ["growth"=0]
/setblock ~ ~ ~ wood ["wood_type"="birch","stripped_bit"=true]
/setblock ~ ~ ~ wool []
```
- Block states are enclosed in square brackets ` [ ] `
- When specifying multiple block states a comma ` , ` is used to separate them.
- Quotation marks ` " " ` are used around strings such as `"birch", "spruce" etc..`
- Integer values `0, 1, 2..` and boolean values `true/false` do not use quotation marks.
- Leaving the brackets blank is also a correct syntax, it will simply default to 0.
- `wool 0` is white wool hence you may simply write it as `wool []` instead of `wool ["color"="white"]`
### Notes For Beginners
- **Integers** are whole numbers. They are used to define a block from a 'range' of values.
- Example: Redstone power 1 to 15
- `["redstone_power"=10]`
- **Boolean** is a programming term which refers to `true/false` values. You can simply understand it as yes or no questions.
- Is this piston powered? `yes/no`
- Is this button pressed? `yes/no`
- Is this log stripped? `yes/no`
- `["stripped_bit"=true]`
- **Strings** are unique 'text' inputs. You can simply understand it as multiple choice questions.
- What color is this wool? `"white"`, `"orange"`, `"brown"` etc..
- What wood type is this log? `"spruce"`, `"birch"`, `"acacia"` etc..
- `["wood_type"="spruce"]`
## Block States List
A list of all the block states currently available within Bedrock can be found at:
https://learn.microsoft.com/en-us/minecraft/creator/reference/content/blockreference/examples/blockstateslist
Note: In the site block states may be written as one word but make sure to separate them with underscores `_` when typing in commands.
Example: `buttonPressedBit` → `"button_pressed_bit"`
## Converting Aux Values to Block States
For your convenience; download any of the excel sheet below to find the full list of block IDs, their aux values and equivalent block states in Bedrock. *Shared by kayla@Mojang*
<BButton
link="https://github.com/BedrockCommands/bedrockcommands.github.io/files/10987839/Aux-Value_to_Block-States_Map.xlsx"
color=white
>Download Sheet 1</BButton>
Note: the above sheet was quickly generated and contains some minor errors. Boolean values `0` should be replaced with `false` and `1` should be replaced with `true` since the game doesn't recognize the syntax otherwise.
Alternate sheet: *Shared by @ItsRichHeart*
<BButton
link="https://github.com/BedrockCommands/bedrockcommands.github.io/files/11069804/All.Block-Item.List.Bedrock.pdf"
color=white
>Download Sheet 2</BButton>
You may also use this [Lookup Table](https://auxval-to-blockstates.netlify.app/) instead not needing to download any files.
## Known Issue
Detecting blocks using commands such as `/execute` or `/testforblock` requires __all__ or __none__ of the block states specified else the command returns an error.
Example; detecting a pressed stone button on ground facing up:
<CodeHeader></CodeHeader>
```yaml
#✅ Accepted:
/execute if block ~~~ stone_button [“button_pressed_bit”=true,”facing_direction”=1] run say success
/execute if block ~~~ stone_button run say success
# ❌ Not Accepted:
/execute if block ~~~ stone_button [“button_pressed_bit”=true] run say success
/execute if block ~~~ stone_button [“facing_direction”=1] run say success
```
Though block states have replaced aux values, we still cannot detect blocks based on specific filters yet like we do with selector arguments.
### Related Bug Reports
- [MCPE-133360](https://bugs.mojang.com/browse/MCPE-133360)
- [MCPE-168391](https://bugs.mojang.com/browse/MCPE-168391)

96
docs/wiki/commands/damage.md Normal file
View File

@@ -0,0 +1,96 @@
---
title: Damage
category: Commands
tags:
- info
mentions:
- BedrockCommands
- cda94581
- jordanparki7
- zheaEvyline
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
Introduced in Minecraft Release `1.18.10`, the /damage command deals precise damage to specified entities. With this change, the clunky methods like using `/effect` command to damage entities are rendered obsolete, making maps and other creations more powerful.
## Syntax
- There are two ways the damage command can be used:
- `/damage <Target> <Amount> [Cause]`
- `/damage <Target> <Amount> <Cause> entity <Damager>`
## Arguments
- Phrases not contained in angle <> or square [] brackets instruct you to type it as-is.
- Phrases contained within brackets are variables, these need to be replaced:
- **` <> `** Angle brackets mean the variable is required.
- **` [] `** Square brackets mean the variable is optional.
## Variables
- **` Target `** This is your typical entity selector, such as `@s` , `@e` , or `"cda94581"` . Multiple entities may be selected at a time to deal the damage to multiple targets.
- **` Amount `** This is a whole number, which specifies the amount of damage to deal to the targets. The minimum value is `0` and the maximum value is `2147483647`, or the signed 32-bit integer limit.
- **` Cause `** This specifies the "reason" the damage was dealt. This cause will appear in death messages (`X hit the ground too hard for cause: fall`) be used in damage calculation with armor (`the value dealt in Amount may be different depending on the worn armor`), and used in a large variety of other things, such as in Behavior Pack/Add-ons. A full list of all the damage causes can be found [below](/commands/damage#damage-cause-list)
- **` Damager `** If Cause was something to do with entities `(such as entity_attack)`, this specifies where the damage came from `(the entity that dealt the attack)`. This is limited to only 1 target. An error will be thrown if multiple targets are found from the selector.
> Note: the `<Cause> entity <Damager>` is only required when the Cause has to do with another entity `(entity_attack)`. Otherwise, follow the first syntax.
## Examples
<CodeHeader>mcfunction</CodeHeader>
```yaml
#Deal 4 damage to all players
/damage @a 4
#Deal 3 'fire' damage to all entities of type 'sheep'
/damage @e [type=sheep] 3 fire
#Deal 40 'entity attack' damage from a random player to all entities of type 'sheep'
/damage @a 40 entity_attack entity @r [type=sheep]
```
## Damage Cause List
Listed below are all the 'damage sources' in MCBE for the `/damage` command currently available:
```
anvil
attack
block_explosion
charging
contact
drowning
entity_attack
entity_explosion
fall
falling_block
fatal
fire
fire_tick
fireworks
fly_into_wall
freezing
lava
lightning
magic
magma
none
override
piston
projectile
sonic_boom
stalactite
stalagmite
starve
suffocation
suicide
temperature
thorns
void
wither
```

89
docs/wiki/commands/entity-counter.md Normal file
View File

@@ -0,0 +1,89 @@
---
title: Entity Counter
category: Scoreboard Systems
mentions:
- BedrockCommands
- zheaEvyline
nav_order: 3
tags:
- system
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
This system allows you to track how many players/entities are there on your world and run your desired commands based on the values obtained.
> Note: you cannot track entities in unloaded chunks though players can still be tracked regardless.
## Setup
*To be typed in Chat:*
`/scoreboard objectives add total dummy`
If you prefer to have the objective added automatically on world initialisation, follow the process outlined in [On First World Load.](/commands/on-first-world-load)
## System
<CodeHeader>BP/functions/entity_counter.mcfunction</CodeHeader>
```yaml
scoreboard players set onlinePlayers total 0
execute as @e [type=player] run scoreboard players add onlinePlayers total 1
#Your Commands Here (examples)
execute if score onlinePlayers total matches 4.. run title @a actionbar Enough players to start game.
execute if score onlinePlayers total matches ..3 run title @a actionbar Not enough players.
```
![commandBlockChain3](/assets/images/commands/commandBlockChain/3.png)
Here we have used a FakePlayer name `onlinePlayers` and targeting `@e [type=player]` to track how many players are currently on the world. However you may use any FakePlayer name and target any entity you might need. Such as `@e [type=creeper]`
Similarly we're running a `/title` command as an example:
- a) when there are 4 or more players `4..`
- b) when there are 3 players or less `..3`
You can edit this as well to suit your need.
## Explanation
- The first two commands in the system sets the FakePlayer name's score to 0 (here `onlinePlayers`) and from each loaded entity we want to track (here `type=player`) it will add a score to the specified FakePlayer name (here `onlinePlayers`)
Now based on the values obtained we can use the `/execute if score` command to run our desired commands when certain values are met.
- **` n `** any number n
- **` n.. `** any number n and above
- **` ..n `** any number n and below
- **` n1..n2 `** any number n1 to any number n2.
## Tick JSON
If you are using functions instead of command blocks, the ` entity_counter ` function must be added to the ` tick.json ` in order to loop and run it continuously. Multiple files can be added to the ` tick.json ` by placing a comma after each string. Refer to [Functions](/commands/mcfunctions#tick-json) documentation for further info.
<CodeHeader>BP/functions/tick.json</CodeHeader>
```json
{
"values": [
"entity_counter"
]
}
```
If using functions, your pack folder structure will be be as follows:
<FolderView
:paths="[
'BP',
'BP/functions',
'BP/pack_icon.png',
'BP/manifest.json',
'BP/functions/entity_counter.mcfunction',
'BP/functions/tick.json'
]"
></FolderView>
> **Note:** the scoreboard names (in this case: 'total') may end up being used by other people. Appending ` _ ` and a set of randomly generated characters after would be a choice that reduces the probability of collisions. Similar technique can be employed for the ` .mcfunction ` filenames. Ex:
> - ` total_0fe678 `
> - ` entity_counter_0fe678.mcfunction `

14
docs/wiki/commands/index.md Normal file
View File

@@ -0,0 +1,14 @@
---
title: Commands
categories:
- title: General
color: green
- title: Commands
color: green
- title: On Event Systems
color: blue
- title: Scoreboard Systems
color: blue
- title: Techniques
color: orange
---

141
docs/wiki/commands/intro-to-command-blocks.md Normal file
View File

@@ -0,0 +1,141 @@
---
title: Intro to Command Blocks
category: General
mentions:
- BedrockCommands
- zheaEvyline
- jordanparki7
nav_order: 1
tags:
- info
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
Command Blocks are special blocks in Minecraft. The same commands (cheats) you type in chat can be run automatically using command blocks and it can be reused without needing to type all over again.
They can only be placed or destroyed by a player with the Operator permission level in gamemode Creative.
## Obtaining
1. Open your world settings.
2. Under Cheats, toggle "Activate Cheats" setting ON.
3. Run `/give @s command_block` command in chat.
## Command Block UI
![commandBlockUI](/assets/images/commands/commandBlockUI.png)
## Command Block Types
![impulseCommandBlock](/assets/images/commands/impulseCommandBlock.png) **Impulse** runs the command __once__ each time it is powered.
![chainCommandBlock](/assets/images/commands/chainCommandBlock.png) **Chain** runs the command in a sequence, ie. only after the previous command block it is connecting from was run.
![repeatingCommandBlock](/assets/images/commands/repeatingCommandBlock.png) **Repeat** runs the command every game tick. There are approximately 20 ticks per second. A delay can be applied to adjust how often the command is executed, explained [below](/commands/intro-to-command-blocks#command-block-tick-delay).
## Command Block Conditions
**Conditional** command blocks will run the command only if the previous command block it was connecting from had an output that was `true` (successful)
> Conditional command block states are shown by a small indent into the command block's texture, as shown below:
> - ![pasteCommandButton](/assets/images/commands/impulseConditionalCommandBlock.png) Impulse Conditional Command Block
> - ![chainConditionalCommandBlock](/assets/images/commands/chainConditionalCommandBlock.png) Chain Conditional Command Block
> - ![repeatingConditionalCommandBlock](/assets/images/commands/repeatingConditionalCommandBlock.png) Repeating Conditional Command Block
**Unconditional** command blocks will run the command regardless. Whether the previous command block it was connecting from had an output that was `true` (succesful), `false` (failed) or even if it came with a syntax error the command block will still run the command.
## Command Block Redstone States
**Needs Redstone** command block can only be activated with redstone power. Using buttons, levers, redstone torch etc..
**Always Active** command block will be activated as soon as you close the command block UI.
## Command Block Tick Delay
In this option you may specify how much delay you want there to be before the command block runs the command.
The ticks refer to Minecraft game ticks. A **tick** is simply a unit of measure for time in games. 1 second in real life is approximately 20 game ticks in Minecraft.
:::tip
![gametick.png](/assets/images/commands/gametick.png)
:::
## Command Block Hover Note
This option allows you to put a hovering text on your command blocks. It's useful for giving short-names for easy identification when working with many command blocks.
When a command is run, the hover note will be displayed with the output in chat if gamerule `commandblockoutput` is enabled.
![hover_note](/assets/images/commands/hover_note.png)
## Paste Button
![pasteCommandButton](/assets/images/commands/pasteCommandButton.png)
The paste button allows you to paste commands from your clipboard to the 'Command Input' box.
## Command Block Output
- Toggle the 'Previous Output' button in the command block UI to see command output and block details.
- The ` / ` you type before the whole command is not required in a command block but doing so won't cause any errors.
- A redstone comparator can read command blocks outputs. If output is true, it will send anywhere from 1 to 15 redstone signals depending on the output value.
- You can check if a command output is `true`/`false` by running it in chat. A red output will be a `false` output or a syntax error. A white output means command was run successfully.
- You can also tell if a command was `true`/`false` by checking whether action was performed or not.
- An output with a value of `0` is usually a false output.
### Disabling Command Messages In Chat
Run in Chat:
- `/gamerule commandblockoutput false` to disable command block messages in chat.
- `/gamerule sendcommandfeedback false` to disable feedback from commands entered in chat.
## Command Block Placement
When placing command blocks in a line (arranged to work together) for any system, make sure the consecutive command blocks connect/start from the head of the arrow.
The arrow/facing direction can be observed from the command block texture.
**✅ Correct Placement**
![correctCommandBlockPlacement](/assets/images/commands/correctCommandBlockPlacement.png)
**❌ Incorrect Placement**
![incorrectCommandBlockPlacement](/assets/images/commands/incorrectCommandBlockPlacement.png)
## Troubleshooting Command Blocks
- In world settings, under **Cheats**, make sure command blocks have not been disabled.
- Make sure gamerule `maxcommandchainlength` is **not** set to 0
- Make sure there are no unwanted redstone power that is interfering with the command block. It can be from redstone dust, lever, redstone torch etc..
- Try switching between Always Active & Needs Redstone.
- Double check the block type, condition & the command syntax. Check 'Previous Output' after powering it once again.
- Just like redstone, command blocks must also be in loaded chunks for them to work. You can use a tickingarea to keep them loaded when players are not nearby. Refer to [/tickingarea](https://learn.microsoft.com/en-us/minecraft/creator/documents/tickingareacommand) command documentation for more info.
If nothing seems to work simply break and place that command block again.
## What you have learned
:::tip What you have learned:
- How to obtain a command block in game.
- How the different types of command blocks behave and what they look like.
- What the different command block options are (including conditional, state and delay.)
- How command blocks output data by redstone and chat messages.
- How to properly place command block chains.
- How to resolve 'command block not working'
:::
To put what you have learned into practice, try making this simple [Entity Counter](/commands/entity-counter) system.
> Note: when setting up command block systems, always the first command will be ![repeatingCommandBlock](/assets/images/commands/repeatingCommandBlock.png) **`Unconditional Always Active`** and the rest will be ![chainCommandBlock](/assets/images/commands/chainCommandBlock.png) **`Unconditional Always Active`** (all 0 ticks delay) *unless specified otherwise.*
>
> ![commandBlockChain4](/assets/images/commands/commandBlockChain/4.png)
**(Recommended) Read Next: [Understanding Selectors](/commands/selectors)**

158
docs/wiki/commands/mcfunctions.md Normal file
View File

@@ -0,0 +1,158 @@
---
title: Functions
category: General
mentions:
- Bedrock Commands
- cda94581
- zheaEvyline
- jordanparki7
nav_order: 3
tags:
- info
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
Functions are `.mcfunction` files which contain multiple lines of commands. They are run with the `/function` command in-game.
Functions are created in a **Behavior Pack**, nested within the **functions** folder. A function pack creates a system using solely function files.
Functions are useful in many ways to reduce the time spent going from command block to command block debugging a system. They also help with packaging systems for use in multiple worlds and provide many functions that can change how everything works.
## Function Pack Folder Structure
<FolderView
:paths="[
'BP',
'BP/functions',
'BP/functions/this_code.mcfunction',
'BP/functions/more_of_this_code.mcfunction',
'BP/functions/tick.json',
'BP/functions/nested',
'BP/functions/nested/this_code_is_nested.mcfunction',
]"
></FolderView>
## Notes For Beginners
<CodeHeader>mcfunction</CodeHeader>
```yaml
#Spawn Effects
effect @a [tag=atSpawn] regeneration 12 255 true
effect @a [tag=atSpawn] saturation 12 255 true
effect @a [tag=atSpawn] weakness 12 255 true
```
- Each new line in a function file represents a new command. You may start a line with # to add comments. Commands in a function do not need to begin with a slash `/`, however doing so will not cause any errors.
- All commands in a function are run in the *same tick*. Because of this, a function which causes large changes may cause a sudden lag spike and it is helpful to delegate some commands across multiple ticks, if possible.
Commands in a function are still run in the same order, however.
- Minecraft can **not** run more than 10,000 lines of commands in one function file. This includes any other function files that are executed inside of the original file.
- It is not possible to run conditional commands. Those will still need to utilize command blocks in some way, or could utilize the 1.19.50 execute syntax.
- Running commands with a specified delay in a function would involve using scoreboard timers to incrementally count up every tick (to a certain point), and executing at certain scores along the file. You may refer to [Scoreboard Timers](/commands/scoreboard-timers) system to learn how to set it up.
## Creating a Function
1. Locate the `📁 com.mojang` folder and navigate to `📁 development_behavior_packs`
- The development folders are used for quick reloading of packs, as the packs aren't cached to the world files.
2. Create a folder (of any name) for the function pack. This will be referred to as Behavior Pack or BP.
3. Create a `📄 manifest.json` file and a `🖼 pack_icon.png` file (optional) within the BP folder.
- A manifest file contains all the information needed to register a pack, while a pack icon displays visually in the pack menu. A pack icon is typically a 128x128 or a 256x256 image, though any power-of-2 resolution will do, they will be upscaled and downscaled accordingly.
<Spoiler title="Sample 📄 manifest.json">
<CodeHeader>BP/manifest.json</CodeHeader>
```json
{
"format_version": 2,
"header": {
"description": "Write Your Pack Description Here",
"name": "Write Your Pack Name Here",
"uuid": "00000000-0000-0000-0000-000000000000",
"version": [ 1, 0, 0 ],
"min_engine_version": [ 1, 19, 73 ]
},
"modules": [
{
"description": "§r",
"type": "data",
"uuid": "00000000-0000-0000-0000-000000000000",
"version": [1, 0, 0 ]
}
]
}
```
Note that the uuid field needs to be replaced with an actual uuid, and the two generated must be different from one another. You can generate a uuid at https://uuidgenerator.net/
</Spoiler>
<Spoiler title="Sample 🖼 pack_icon.png">
Sample A:
![pack_icon.png](/assets/images/commands/pack_icon.png)
Sample B:
![pack_icon.png](/assets/images/guide/project-setup/pack_icon.png)
</Spoiler>
4. Create a `📁 functions` folder. Any file within this folder that ends with **.mcfunction** will be registered as a function in-game, which can be run with `/function <function_name>`.
- Nested functions are allowed, simply list the file path in relation to the functions folder as shown in the function pack folder structure.
5. Apply the behavior pack in-game and try out the functions. Function file changes can be reflected in the world by running `/reload` or by simply relogging.
:::tip NOTE
Functions are versioned; therefore, they will run in the version listed in the `📄 manifest.json`, such as:
- `min_engine_version` 1.19.50 or above will adopt the new execute syntax.
- `min_engine_version` 1.19.70 or above will require aux values be replaced with block states.
:::
## Execution
Functions can be executed in-game by typing `/function name_of_function`. This will execute all the commands in the function file, all in a single tick.
Nested functions, for example `BP/functions/lobby/items/1.mcfunction` can be run using the nested folder path, in this case `/function lobby/items/1`
## tick.json
The final file within a function is the **tick.json** file. This specifies functions to run server-side on every game tick, (similar to a repeating command block.) It is located in the `BP/functions` folder. By default, functions running in this file execute at origin `0, 0, 0` in the overworld.
<CodeHeader>BP/functions/tick.json</CodeHeader>
```json
{
"values": [
"function_1",
"function_2"
]
}
```
> Note: functions in this file are run as soon as the world is *initialized*, regardless of whether or not the player has been *loaded*. This may cause unintended behavior if used incorrectly.
## Sample Function Pack
<CardLink
imgsrcLight="assets/images/commands/BClogo.png"
title="Download Sample Function Pack"
link="https://github.com/Bedrock-OSS/wiki-addon/releases/download/download/functions_sample.mcpack"
/>
## Troubleshooting Functions
Your functions may not appear within the command suggestions when using `/function`. This is normally due to an error with one or more commands in the function.
Enabling the [Content Log](/guide/troubleshooting#content-log) in creator settings will allow you to see if there are any errors in your function pack, in which function the error is in, at which line and exactly what the syntax error for that command is.
The list of errors will be generated every time you load a world or run `/reload` to reflect changes after editing files. The list can be viewed on-screen for a few seconds as well as in the content log history in settings.
![contentLogToggles](/assets/images/commands/contentLogToggles.png)
![contentLogHistory](/assets/images/commands/contentLogHistory.png)

108
docs/wiki/commands/nbt-commands.md Normal file
View File

File diff suppressed because one or more lines are too long

247
docs/wiki/commands/new-execute.md Normal file
View File

@@ -0,0 +1,247 @@
---
title: New Execute
category: Commands
tags:
- easy
mentions:
- JaylyDev
- Sprunkles137
- Hatchibombotar
- TheItsNameless
- SmokeyStack
- zheaEvyline
---
## Introduction
With the release of 1.19.50, the `/execute` command was given a syntax overhaul. While the syntax is now more verbose and longer to write, it allows much finer control over the contextual components of commands and adds support for conditions to commands, superseding the use of commands like `/testfor`, `/testforblock`, and `/testforblocks`.
Before we dive into the syntax and how to write it, we need to understand how the old `/execute` command worked, and what changed and why. This will make explaining the concepts found in the syntax easier.
## Understanding Execution Context
For both beginners to commands and those well versed in how old `/execute` behaved, it may be a good idea to review the concept of a command's **execution context**.
In short, these are the parameters that affects how a command runs. Who the command will run as, also known as its executor; where the command will run, and in which dimension; and the rotation applied to the command are all parameters that can be changed.
Every command has this context applied to it, and this context changes depending on how the command runs. Commands fired from command blocks do not have an executor, and the position is set to that command block; commands ran from chat define the executor as the player, and it runs at the player's position.
## Execute, and Why it Changed
The `/execute` command executes a command on behalf of one or more entities. The old syntax used to be this:
```
/execute <target> <position> <command>
/execute <target> <position> detect <position> <block> <data value> <command>
```
You specified a target to execute as, then the command's context would change to run as that target, and at that target. Any position changes were then always relative to that target.
While this is useful in most cases, it also forces the fact that a command's target and its position are always tied together (unless you were to manually insert world coordinates in place of `<position>`). It is also not very malleable in regards to making conditional statements, as you have to execute as an entity every time.
Back in the Summer of 2017 during the Update Aquatic's development, the developers of Minecraft: Java Edition were getting feedback from the community on how they can improve the `/execute` command's syntax, and the basic concept that was conceived is this: `/execute` takes an unlimited number of **subcommands** that manipulate certain aspects of the command in the order you specify, then a "run" subcommand is placed at the end to fire a command.
This allows for much greater control for what `/execute` can do to a command, and allows splitting up the executor and the command's position.
## New Syntax
Now, let us review the new `/execute` syntax. They are as follows:
### `/execute as`
Changes the executor of the command, or what the target selector `@s` will select.
```
/execute as <origin: target> -> execute
```
This does not change the position, rotation, or dimension context of the command.
If multiple targets are specified then a command is ran once for each target, where `@s` selects each entity in turn.
### `/execute at`
Changes where the command runs, setting the command's position, rotation, and dimension context to the entity.
```
/execute at <origin: target> -> execute
```
This does not change the executor of the command, so `@s` will remain as whoever was targeted last.
If multiple targets are specified then a command is ran once for each target, setting the position, rotation, and dimension context to each target.
### `/execute in`
Sets the dimension in which the command should run.
```
/execute in <dimension: string> -> execute
```
Currently accepted values are `overworld`, `nether`, and `the_end`.
This change in dimension will respect that dimension's scale; going from the Overworld to The Nether will apply a scale of x0.125 to the position, and vice versa will apply a x8 scale to the position.
### `/execute positioned`
Directly sets the position context of the command.
```
/execute positioned <position: x y z> -> execute
```
Sets the position of the command to specific values. [Relative and local coordinates](/commands/relative-coordinates) are based around the current position of the command.
```
/execute positioned as <origin: target> -> execute
```
Sets the position of the command to a target's location. This is similar to how `/execute at` works, but it only sets the command's position and not its rotation or dimension.
If multiple targets are specified then a command is ran once for each target, setting the position context to the target's position.
### `/execute align`
Aligns the current position of the command to the block grid.
```
/execute align <axes: swizzle> -> execute
```
Aligning a position will floor it. This subcommand accepts any non-repeating combination of the letters "x", "y", and "z", and will floor the position along each axis specified.
### `/execute anchored`
Sets the anchor of the command to the executor's feet or eyes. Changing the anchor will affect the position where local coordinates will start at.
```
/execute anchored (eyes|feet) -> execute
```
The default anchor when executing at a target is their feet.
When the anchor is set to `eyes`, the command's local position is offset by some amount corresponding to the "eye height" of the current executor.
This offset should only apply to local coordinates, but it currently affects relative coordinates due to a bug: [MCPE-162681](https://bugs.mojang.com/browse/MCPE-162681).
### `/execute rotated`
Directly sets the rotation context of the command.
```
/execute rotated <yaw: value> <pitch: value> -> execute
```
Sets the rotation of the command to specific values. Relative and local coordinates are based around the current rotation of the command. This defaults to 0 for both pitch and yaw, unless the rotation was changed prior.
```
/execute rotated as <origin: target> -> execute
```
Sets the rotation of the command to a target's rotation.
If multiple targets are specified then a command is ran once for each target, setting the rotation context to the target's rotation.
### `/execute facing`
Sets the rotation of the command to face some position. This rotation is calculated based on the current position of the command.
```
/execute facing <position: x y z> -> execute
```
Sets the rotation to face a block position. Relative and local coordinates are based around the current position of the command.
```
/execute facing entity <origin: target> (eyes|feet) -> execute
```
Sets the rotation to face a target's position. Setting the anchor to `feet` will aim the rotation to face where they are currently standing, while setting the anchor to `eyes` will aim the command up at the "eye position" of that target (see [`/execute anchored`](/commands/new-execute#execute-anchored)).
If multiple targets are specified then a command is ran once for each target, setting the rotation context to face that target.
### `/execute (if|unless)`
Prevents running a command based on a condition. If the condition is true then the command will continue, or stop otherwise.
`/execute unless` acts as the opposite, testing if the condition is false in order to continue.
```
/execute if entity <target: target> -> execute
```
Acts like `/testfor`. Returns true if the targets exist.
```
/execute if block <position: x y z> <block: string> -> execute
```
Acts like `/testforblock`. Returns true if the block at the specified location exists.
A data value or block state may additionally be specified, otherwise it ignores block states (acts as if it were set to `-1`).
```
/execute if blocks <begin: x y z> <end: x y z> <destination: x y z> (all|masked) -> execute
```
Acts like `/testforblocks`. It constructs a volume between the beginning and end positions, and returns true if the volume at the destination matches the original volume.
The parameter `all` tests that all blocks must match, while `masked` will ignore air blocks.
```
/execute if score <target: target> <objective: string> matches <range: integer range> -> execute
```
Tests if a specified score is a certain value. This uses the integer range syntax.
```
/execute if score <target: target> <objective: string> (=|<|<=|>|>=) <source: target> <objective: string> -> execute
```
Tests if a specified score matches some logical comparison to another score. Operators are equals (`=`), greater than (`>`), greater than or equal to (`>=`), less than (`<`), and less than or equal to (`<=`).
### `/execute run`
```
/execute run <command: command>
```
Runs a command using all of the currently applied context modifications. This subcommand always goes last in one `/execute` command.
This subcommand is not always required however; an `/execute` command ending with an `if` or `unless` subcommand is valid too, and will return the success of the test it performed.
## Examples and Upgrading Old Commands
Since subcommands can be chained limitlessly, there really is a nearly infinite combination of arguments for an `/execute` command and they cannot all be listed. Instead, listed here are some common examples of commands.
The old functionality of `/execute` can be replicated with `as <target> at @s`. If you need a positional offset relative to the entity, add `positioned`. If you want to detect if a block is present, add `if block`. Here are some equivalents:
```
# Teleport with an offset
/execute @p ~ ~1.62 ~ teleport @s ^ ^ ^3
/execute as @p at @s positioned ~ ~1.62 ~ run teleport @s ^ ^ ^3
```
```
# Chaining multiple '/execute's
/execute @e[type=sheep] ~ ~ ~ execute @e[type=item,r=5] ~ ~ ~ detect ~ ~-1 ~ stone 0 kill @s
/execute at @e[type=sheep] as @e[type=item,r=5] at @s if block ~ ~-1 ~ stone 0 run kill @s
```
(Note that we do not use `as @e[type=sheep] at @s` because we do not need to execute as the sheep; only the position here is required.)
Now for some examples of things that were not possible to do in one command, or were more difficult to perform before the new syntax was introduced.
```
# Testing a fake player's score
/execute if score game_settings var matches 3.. run say [Game] Difficulty set to Hard.
# Comparing if two scores are equal
/execute as @a if score @s x = @s y run say My X is equal to my Y.
# Test for an entity without targeting it
/execute as @a at @s if entity @e[type=armor_stand,r=10] run gamemode survival @s
```

73
docs/wiki/commands/on-first-join.md Normal file
View File

@@ -0,0 +1,73 @@
---
title: On First Join
category: On Event Systems
mentions:
- BedrockCommands
- zheaEvyline
- SmokeyStack
nav_order: 1
tags:
- system
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
This system will run your desired commands on the event that a player joins the world for the first time.
## System
<CodeHeader>BP/functions/on_first_join.mcfunction</CodeHeader>
```yaml
#Your Commands Here (examples)
give @a [tag=!joined] stone_pickaxe
give @a [tag=!joined] bread 16 1
tag @a [tag=!joined] add joined
```
![commandBlockChain3](/assets/images/commands/commandBlockChain/3.png)
Here we have used 2 `give` commands as example but you can use any command you prefer and as many as you require.
Just make sure to follow the given order and properly add the selector argument ` tag=!joined ` as shown for your desired commands.
## Explanation
When the player joins the world for the first time, they will not have the joined tag.
Once we run our desired commands for players without the tag, they will be given the tag immediately and the commands will not repeat for them again unless we remove their tag with:
`tag <player> remove joined`
## Tick JSON
If you are using functions instead of command blocks, the ` on_first_join ` function must be added to the ` tick.json ` in order to loop and run it continuously. Multiple files can be added to the ` tick.json ` by placing a comma after each string. Refer to [Functions](/commands/mcfunctions#tick-json) documentation for further info.
<CodeHeader>BP/functions/tick.json</CodeHeader>
```json
{
"values": [
"on_first_join"
]
}
```
If using functions, your pack folder structure will be be as follows:
<FolderView
:paths="[
'BP',
'BP/functions',
'BP/pack_icon.png',
'BP/manifest.json',
'BP/functions/on_first_join.mcfunction',
'BP/functions/tick.json'
]"
></FolderView>
> **Note:** the tag names (in this case: 'joined') may end up being used by other people. Appending ` _ ` and a set of randomly generated characters after would be a choice that reduces the probability of collisions. Similar technique can be employed for the ` .mcfunction ` filenames. Ex:
> - ` joined_0fe678 `
> - ` on_first_join_0fe678.mcfunction `

78
docs/wiki/commands/on-first-world-load.md Normal file
View File

@@ -0,0 +1,78 @@
---
title: On First World Load
category: On Event Systems
mentions:
- BedrockCommands
- zheaEvyline
- SmokeyStack
- cda94581
nav_order: 6
tags:
- system
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
This system will run your desired commands on the event that the world is loaded for the first time.
> **Note:** a [Function](/commands/mcfunctions) Pack is required to achieve this system since it is the `tick.json` file which allows us to run commands as soon as the world is initialised.
## Tick Json
<CodeHeader>BP/functions/tick.json</CodeHeader>
```json
{
"values": [
"initialise"
]
}
```
## System
<CodeHeader>BP/functions/initialise.mcfunction</CodeHeader>
```yaml
scoreboard objectives add world dummy
scoreboard players add initialised world 0
#Your Commands Here (example)
execute if score initialised world matches 0 run say New world created!
scoreboard players set initialised world 1
```
Here we have used an `execute - say` command as an example but you can use any command you prefer and as many as you require.
Just make sure to follow the given order and properly use the `execute if score` command as shown to run the commands you need.
## Explanation
- **` initialised=0 `** this means the world has just initialised and we are yet to run the initlisation commands.
- **` initialised=1 `** this means the world has been initialised and we have already run the initialisation commands.
An objective of the name `world` is added for us to save scores to it so that we can track whether the world has been initialised or not. This also allows us to structure our commands to only execute at world initialisation.
Following the creation of the objective, a score of `0` is added to the FakePlayer name `initialised`. This will register it to the objective and enable us to use the `execute if score` command structure to run our desired commands.
Finally the score for `initialised` is set to 1 after all the commands are run in order to prevent it from executing more than once.
## Folder Structure
<FolderView
:paths="[
'BP',
'BP/functions',
'BP/pack_icon.png',
'BP/manifest.json',
'BP/functions/initialise.mcfunction',
'BP/functions/tick.json'
]"
></FolderView>
> **Note:** the scoreboard names (in this case: 'world') may end up being used by other people. Appending ` _ ` and a set of randomly generated characters after would be a choice that reduces the probability of collisions. Similar technique can be employed for the ` .mcfunction ` filenames. Ex:
> - ` world_0fe678 `
> - ` initialise_0fe678.mcfunction `

95
docs/wiki/commands/on-player-death.md Normal file
View File

@@ -0,0 +1,95 @@
---
title: On Player Death
category: On Event Systems
mentions:
- BedrockCommands
- zheaEvyline
nav_order: 4
tags:
- system
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
This system will run your desired commands on the event that a player dies.
## Setup
*To be typed in Chat:*
`/scoreboard objectives add alive dummy`
If you prefer to have the objective added automatically on world initialisation, follow the process outlined in [On First World Load.](/commands/on-first-world-load)
## System
<CodeHeader>BP/functions/on_player_death.mcfunction</CodeHeader>
```yaml
scoreboard players set @a [scores={alive=!2}] alive 0
scoreboard players set @e [type=player] alive 1
#Your Commands Here (example)
execute as @a [scores={alive=0}] run say I died
scoreboard players set @a [scores={alive=0}] alive 2
```
![commandBlockChain4](/assets/images/commands/commandBlockChain/4.png)
Here we have used an `/execute - say` command as an example but you can use any command you prefer and as many as you require.
Just make sure to follow the given order and properly add the selector argument ` scores={alive=0} ` as shown for your desired commands.
## Explanation
- **` alive=0 `** this means player is dead.
- **` alive=1 `** this means player is alive.
- **` alive=2 `** this means player is dead and we have run our desired commands on/from them.
- **` @a `** selector will target all players alive/dead so we use it to mark everyone as 0 'dead.'
- Note: we will ignore 2 or it will end up making the commands execute on dead players again. We only want our commands to execute once.
- **` @e `** selector on the other hand will only target players who are alive, so we can use this to mark all alive players 1 'alive.'
- Now that dead players are 0 and alive players are 1 we can use this knowledge to run our desired commands on the dead players.
- Keep in mind we need to set their score to 2 after or otherwise the commands will keep executing till they respawn.
## Tick JSON
If you are using functions instead of command blocks, the ` on_player_death ` function must be added to the ` tick.json ` in order to loop and run it continuously. Multiple files can be added to the ` tick.json ` by placing a comma after each string. Refer to [Functions](/commands/mcfunctions#tick-json) documentation for further info.
<CodeHeader>BP/functions/tick.json</CodeHeader>
```json
{
"values": [
"on_player_death"
]
}
```
If using functions, your pack folder structure will be be as follows:
<FolderView
:paths="[
'BP',
'BP/functions',
'BP/pack_icon.png',
'BP/manifest.json',
'BP/functions/on_player_death.mcfunction',
'BP/functions/tick.json'
]"
></FolderView>
> **Note:** the scoreboard names (in this case: 'alive') may end up being used by other people. Appending ` _ ` and a set of randomly generated characters after would be a choice that reduces the probability of collisions. Similar technique can be employed for the ` .mcfunction ` filenames. Ex:
> - ` alive_0fe678 `
> - ` on_player_death_0fe678.mcfunction `

86
docs/wiki/commands/on-player-join.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: On Player Join
category: On Event Systems
mentions:
- BedrockCommands
- zheaEvyline
nav_order: 2
tags:
- system
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
This system will run your desired commands on the event that a players joins the world.
## Setup
*To be typed in Chat:*
`/scoreboard objectives add joined dummy`
If you prefer to have the objective added automatically on world initialisation, follow the process outlined in [On First World Load.](/commands/on-first-world-load)
## System
<CodeHeader>BP/functions/on_player_join.mcfunction</CodeHeader>
```yaml
scoreboard players add @a joined 0
#Your Commands Here (example)
tp @a[scores={joined=0}] 0 65 0
scoreboard players reset * joined
scoreboard players set @a joined 1
```
![commandBlockChain4](/assets/images/commands/commandBlockChain/4.png)
Here we have used a `tp` command as an example but you can use any command you prefer and as many as you require.
Just make sure to follow the given order and properly add the selector argument ` scores={joined=0} ` as shown for your desired commands.
## Explanation
When the player joins, a 0 is added to their objective, this allows us to run commands from them using the 'scores' selector argument.
Immediately after the commands are run, we reset all the scores on the objective using wildcard **` * `** and only players who stayed online will have their score set to 1.
And this way, since our commands only target players with the score 0, the commands won't repeat again for the players who stayed unless they leave and rejoin or if we run:
`/scoreboard players set <player> joined 0`
## Tick JSON
If you are using functions instead of command blocks, the ` on_player_join ` function must be added to the ` tick.json ` in order to loop and run it continuously. Multiple files can be added to the ` tick.json ` by placing a comma after each string. Refer to [Functions](/commands/mcfunctions#tick-json) documentation for further info.
<CodeHeader>BP/functions/tick.json</CodeHeader>
```json
{
"values": [
"on_player_join"
]
}
```
If using functions, your pack folder structure will be be as follows:
<FolderView
:paths="[
'BP',
'BP/functions',
'BP/pack_icon.png',
'BP/manifest.json',
'BP/functions/on_player_join.mcfunction',
'BP/functions/tick.json'
]"
></FolderView>
> **Note:** the scoreboard names (in this case: 'joined') may end up being used by other people. Appending ` _ ` and a set of randomly generated characters after would be a choice that reduces the probability of collisions. Similar technique can be employed for the ` .mcfunction ` filenames. Ex:
> - ` joined_0fe678 `
> - ` on_player_join_0fe678.mcfunction `

107
docs/wiki/commands/on-player-leave.md Normal file
View File

@@ -0,0 +1,107 @@
---
title: On Player Leave
category: On Event Systems
mentions:
- BedrockCommands
- zheaEvyline
nav_order: 3
tags:
- system
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
This system will run your desired commands on the event that a player leaves the world.
> **Note:** you cannot execute commands on the *players* that leave using selectors. However; you may use the [On Player Join](/commands/on-player-join) system to execute when they join back.
## Setup
*To be typed in Chat:*
`/scoreboard objectives add total dummy`
If you prefer to have the objective added automatically on world initialisation, follow the process outlined in [On First World Load.](/commands/on-first-world-load)
## System
<CodeHeader>BP/functions/on_player_leave.mcfunction</CodeHeader>
```yaml
scoreboard players reset new total
execute as @a run scoreboard players add new total 1
scoreboard players operation new total -= old total
#Your Commands Here (example)
execute if score new total matches ..-1 run say a player has left the world
scoreboard players reset old total
execute as @a run scoreboard players add old total 1
```
![commandBlockChain6](/assets/images/commands/commandBlockChain/6.png)
Here we have used a **`/say`** command as an example but you can use any command you prefer and as many as you require.
Just make sure to follow the given order and properly use the `/execute if score` command as shown to run the commands you need.
## Explanation
- **` new `** this FakePlayer name means the total number of players on the world in the current game tick.
- **` old `** this FakePlayer name means the total number of players that were on the world in the previous game tick but also saves the values to be used in the *next* game tick.
These values are obtained using the [Entity Counter](/commands/entity-counter) system. It may be beneficial to refer to that doc for better understanding this one.
By subtracting 'old' total from 'new' total we will be able to identify if player count has:
- decreased ` ..-1 `
- increased ` 1.. `
- or if it's unchanged ` 0 `
If it has decreased; we know that 1 or more players have left the game.
With this knowledge we can run our desired commands from 'new' if it's score is -1 or less.
- ie, if there were 10 players and someone leaves:
- that is ` new - old `
- which is ` 9 - 10 = -1 `
- hence we will detect by ` ..-1 `
- The 'new' total value is obtained first, subtraction is performed after that to run your desired commands and lastly the 'old' total value is obtained to be used in the next game tick.
:::tip
All commands involved in a command-block-chain or function will only run in a sequence one after the other but it all still happens in the same tick regardless of the number of commands involved. We are able to achieve this system due to the fact that commands run along the end of a game tick after all events such as player log in, log out, death etc.. occur.
![gametick](/assets/images/commands/gametick.png)
:::
## Tick JSON
If you are using functions instead of command blocks, the ` on_player_leave ` function must be added to the ` tick.json ` in order to loop and run it continuously. Multiple files can be added to the ` tick.json ` by placing a comma after each string. Refer to [Functions](/commands/mcfunctions#tick-json) documentation for further info.
<CodeHeader>BP/functions/tick.json</CodeHeader>
```json
{
"values": [
"on_player_leave"
]
}
```
If using functions, your pack folder structure will be be as follows:
<FolderView
:paths="[
'BP',
'BP/functions',
'BP/pack_icon.png',
'BP/manifest.json',
'BP/functions/on_player_leave.mcfunction',
'BP/functions/tick.json'
]"
></FolderView>
> **Note:** the scoreboard names (in this case: 'total') may end up being used by other people. Appending ` _ ` and a set of randomly generated characters after would be a choice that reduces the probability of collisions. Similar technique can be employed for the ` .mcfunction ` filenames. Ex:
> - ` total_0fe678 `
> - ` on_player_leave_0fe678.mcfunction `

86
docs/wiki/commands/on-player-respawn.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: On Player Respawn
category: On Event Systems
mentions:
- BedrockCommands
- zheaEvyline
nav_order: 5
tags:
- system
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
This system will run your desired commands on the event that a player respawns from death state.
## Setup
*To be typed in Chat:*
`/scoreboard objectives add respawn dummy`
If you prefer to have the objective added automatically on world initialisation, follow the process outlined in [On First World Load.](/commands/on-first-world-load)
## System
<CodeHeader>on_player_respawn.mcfunction</CodeHeader>
```yaml
#Your Commands Here (example)
execute as @e [scores={respawn=1}] run say I died and respawned.
scoreboard players set @a respawn 1
scoreboard players set @e [type=player] respawn 0
```
![commandBlockChain3](/assets/images/commands/commandBlockChain/3.png)
Here we have used an `/execute - say` command as an example but you can use any command you prefer and as many as you require.
Just make sure to follow the given order and properly use the selector argument ` @e [scores={respawn=1}] ` as shown for your desired commands.
## Explanation
- **` respawn=0 `** this means the player is alive or had already respawned.
- **` respawn=1 `** this means the player died and is now respawning, ie. respawned *just now*, in the current gametick.
- **` @a `** selector will target all players alive/dead so we use it to mark everyone as 1 'respawning'
- **` @e `** selector on the other hand will only target players who are alive, so we can use this to mark all alive players 0 'respawned'
Now that *respawning* players are 1 and *respawned* players are 0 we can use this knowledge to run our desired commands on the players respawning.
In the system, your desired commands must come before the other 2 commands because players change from death state to alive state along the start of the gametick before commands are run.
Hence; if we were to put them at the end then the other 2 commands would set respawning players score to 0 first and then the commands you want to run won't be able to select those players as our selector argument is ` @e [scores={respawn=1}] ` not 0. Using 0 would not work as then it would repeat endlessly even on players who have already respawned.
## Tick JSON
If you are using functions instead of command blocks, the ` on_player_respawn ` function must be added to the ` tick.json ` in order to loop and run it continuously. Multiple files can be added to the ` tick.json ` by placing a comma after each string. Refer to [Functions](/commands/mcfunctions#tick-json) documentation for further info.
<CodeHeader>BP/functions/tick.json</CodeHeader>
```json
{
"values": [
"on_player_respawn"
]
}
```
If using functions, your pack folder structure will be be as follows:
<FolderView
:paths="[
'BP',
'BP/functions',
'BP/pack_icon.png',
'BP/manifest.json',
'BP/functions/on_player_respawn.mcfunction',
'BP/functions/tick.json'
]"
></FolderView>
> **Note:** the scoreboard names (in this case: 'respawn') may end up being used by other people. Appending ` _ ` and a set of randomly generated characters after would be a choice that reduces the probability of collisions. Similar technique can be employed for the ` .mcfunction ` filenames. Ex:
> - ` respawn_0fe678 `
> - ` on_player_respawn_0fe678.mcfunction `

79
docs/wiki/commands/playsound.md Normal file
View File

@@ -0,0 +1,79 @@
---
title: Playsound
category: Commands
mentions:
- BedrockCommands
- zheaEvyline
- jordanparki7
tags:
- info
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
You can use the `/playsound` command to play sound effects to players present anywhere in the world whenever you like.
## Syntax
`/playsound <sound> [player] [position] [volume] [pitch] [minimumVolume]`
## Definitions
### Sound
- It is the sound effect you wish to play.
- You can find the list of sound IDs currently available at:
- https://www.digminecraft.com/lists/sound_list_pe.php
### Player
- This is an optional argument.
- It refers to your typical target selectors (whom you want to play the sound to) ` @a `, ` @r `, ` @p `, ` Technoblade `, etc..
### Position
- This is an optional argument.
- It refers to the `x y z` position from where the sound will be played, ie. the center of the playsound radius.
### Volume
- This is an optional argument.
- It determines the size of the sphere in which the sound effect can be heard.
- ` 0.0 ` is the minimum size.
- Sound & audible sphere size increases as `volume` value is increased.
- Playaound volume of `1` is equal to an audible sphere of radius 16 blocks.
- Similarly; volume of `4` would be equal to 64 blocks.
### Pitch
- This is an optional aegument.
- It determines the pitch for the sound effect.
- It can be a value between ` 0.0 ` and ` 256.0 `
- The higher the value, the higher the pitch.
- Values less than or equal to `0.0` makes the sound inaudible.
> Note: pitch affects the speed at which the audio is played. For example, a pitch of `0.5` would mean the audio is played at ` 0.5× ` speed.
### Minimum Volume
- This is an optional argument.
- It determines the minimum volume at which the sound will be heard outside of the audible sphere.
- It can be a value between ` 0.0 ` and ` 1.0 `
## Examples
<CodeHeader>mcfunction</CodeHeader>
```yaml
#Play a random explosion sound effect to closest player.
/playsound random.explode @p
#Play a random orb sound effect to all players at their relative position with a volume of 10000
/execute as @a at @s playsound random.orb @s ~ ~ ~ 10000
```
Note: since the playsound command is positonal, it is helpful to use an execute command structure as shown in the second example to prevent the sound effect from cutting off in special cases such as playing a sound effect following a `/tp` command. You may increase volume when covering large distances to reduce failures.
**(Recommended) Read Next: [Sounds](/concepts/sounds)**

46
docs/wiki/commands/relative-coordinates.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: Coordinate System
category: General
mentions:
- MedicalJewel105
- Sprunkles137
- 7dev7urandom
- Hatchibombotar
- TheItsNameless
---
## The Coordinate System
Minecraft stores the locations of blocks and entities in the world using a system of three-dimensional coordinates, each representing a value in a one-dimensional axis. They are stored in the format of X, then Y, and lastly Z. Whether you are placing structures and blocks, or teleporting and summoning entities, you can, and are sometimes required to, put in coordinates. They don't need to always be real values however; you can substitute world coordinates for relative values, either based in world space or local space.
![image](https://user-images.githubusercontent.com/64864915/134789891-85644dd7-e30f-4e02-966c-df2bf17a7879.png)
_You may already be familiar with coordinates if you've enabled the Show Coordinates world option!_
## Relative Coordinates (~)
Relative coordinates are represented using tildes in place of real coordinates, and represent a position that is relative to the world coordinates its located at. You may insert numbers after a tilde to add an offset to the current position. These can be mixed with world coordinates, but cannot be mixed with local coordinates.
Examples:
- `~ ~ ~`: Current position with no changes.
- `~5 ~-2 ~`: Current position with a 5-block X offset and a negative 2-block Y offset.
### Rotations
Relative coordinates can also be used in the context of rotations, where they represent a rotation that is relative to the current rotation it inherits from. These may also accept numbers after the tilde to add an offset to the current rotation.
Example: `~90 ~` will add 90° to the current yaw (y-rotation) value.
## Local Coordinates (^)
Local coordinates are similar to relative coordinates, but represent a position in local space, where the axes are based off of rotation. They take the form `^left ^up ^forward`; you can think of this as `~x ~y ~z` if both your yaw and pitch rotations are 0 (facing straight ahead, due south).
Like relative coordinates, you can insert numbers to produce an offset of the current position, in local space. If there is no entity to copy rotation from, the x- and y-rotations are assumed to be 0.
Examples:
- `^10 ^ ^`: Current position with a 10-block offset to the left.
- `^ ^1.5 ^1`: Current position with a 1.5-block offset upward and a 1-block offset forward.
## Additional Notes
- The player's eye level is 1.62 blocks above their feet. (~ ~1.62 ~)

135
docs/wiki/commands/scoreboard-operations.md Normal file
View File

@@ -0,0 +1,135 @@
---
title: Scoreboard Operations
category: General
mentions:
- Sprunkles137
- Luthorius
- MedicalJewel105
- Hatchibombotar
---
Scoreboards can be used to perform complex operations, similar to [Molang](/concepts/molang). Operations come in two flavors: mathematical, and logical.
## Overview
Operations are performed using the `/scoreboard players operation` command. The full syntax is laid out below:
```
/scoreboard players operation <targetScore> <objective> <operation> <sourceScore> <objective>
```
The command consists of two score holders: The target score, and the source score. The target score is the value being operated on, and the source score is the value affecting the operation. The result of the operation is written into the target score, and the source score's value is not touched, save for [one operation](/commands/scoreboard-operations#swap-operator).
## Mathematical Operators
Mathematical operators use arithmetic to affect the target score. There are five mathematical operations available: addition, subtraction, multiplication, floor division, and floor modulo division.
For each of the following examples below, assume that score holder `A var` equals 25, and `B var` equals 10.
### Addition
Operator: **+=**
This operation adds the target score and source scores together, then stores the sum into the target score.
```
/scoreboard players operation A var += B var
```
`A = A + B`, and as such `25 + 10 = 35`.
### Subtraction
Operator: **-=**
This operation subtracts the target score by the source score, then stores the difference into the target score.
```
/scoreboard players operation A var -= B var
```
`A = A - B`, and as such `25 - 10 = 15`.
### Multiplication
Operator: **\*=**
This operation multiplies the target score by the source score, then stores the product into the target score.
```
/scoreboard players operation A var *= B var
```
`A = A * B`, and as such `25 * 10 = 250`.
### Floored Division
Operator: **/=**
This operation divides the target score by the source score, then stores the quotient into the target score. Because score values can only be integers, the value is floored, or rounded down.
```
/scoreboard players operation A var /= B var
```
`A = floor(A / B)`, and as such `floor(25 / 10) = 2`.
### Floored Modulo Division
Operator: **%=**
This operation also divides the target score by the source score, but instead returns the remainder after the division into the target score. This is also floored.
```
/scoreboard players operation A var %= B var
```
`A = floor(mod(A, B))`, and as such `floor(mod(25, 10)) = 5`.
## Logical Operators
Logical operations use logic gates and assignments to affect the target score. There are four logical operations available: assignment, less than, greater than, and swap.
Similar to the above, assume that score holder `A var` equals 25, and `B var` equals 10.
### Assignment Operator
Operator: **=**
This operation sets the target score equal to the source score.
```
/scoreboard players operation A var = B var
```
`A = B`, and as such the result is `10`.
### Minimum Operator
Operator: **<**
This operation returns the smallest of the input scores, and stores it into the target score.
```
/scoreboard players operation A var < B var
```
`A = min(A, B)`, and as such `min(25, 10) = 10`.
### Maximum Operator
Operator: **>**
This operation returns the largest of the input scores, and stores it into the target score.
```
/scoreboard players operation A var > B var
```
`A = max(A, B)`, and as such `max(25, 10) = 25`.
### Swap Operator
Operator: **><**
This operation swaps the target score and source scores with each other. This is the only operation that affects the source score.
```
/scoreboard players operation A var >< B var
```
The above command would swap the values of A and B e.g.
Before: A = 10; B = 25;
After: A = 25; B = 10;
This can be seen as three operations: `temp = A; A = B; B = temp;`, and as such `A var = 10` and `B var = 25`.
## Useful Creations
#### Check If Values are Equal
If you want to check in scoreboard, whether one value equals another value, you can copy first value to temporary value, subtract the other and compare temporary value to zero. Given values A and B:
<CodeHeader></CodeHeader>
```
scoreboard objectives add temp dummy
scoreboard players operation @e temp = @s A
scoreboard players operation @e temp -= @s B
execute @e[scores={temp=0}] ~~~ say A equals B
scoreboard objectives remove temp
```
#### Scoreboard Initialization
If you want to initialize a scoreboard value to 0, but only if it doesn't exists, you can use `scoreboard players add <selector> <name> 0`. It will set the value to 0, if it doesn't exist on the entity and do nothing, if it already exist.

200
docs/wiki/commands/scoreboard-timers.md Normal file
View File

@@ -0,0 +1,200 @@
---
title: Scoreboard Timers
category: Scoreboard Systems
mentions:
- BedrockCommands
- zheaEvyline
nav_order: 5
tags:
- system
---
## Introduction
[Sourced By Bedrock Commands Community Discord](https://discord.gg/SYstTYx5G5)
This system allows you to run your desired commands at specific intervals with any amount of delay that you wish to add.
- **Some Examples:**
- Sending a message in chat every 2 hours.
- Running a 'lag clear' function every 10 minutes.
- Effecting players with 'speed' every 30 seconds.
This system is especially useful when you need to set up multiple timers on your world. When working with command blocks, you may use the [Tick Delay](/commands/intro-to-command-blocks#command-block-tick-delay) option to delay the time taken for your commands to run. However, when working with functions you will need to use a system like this.
It is recommended to use this system while working with command blocks, as well if you wish to run all your timers in sync with one another, ie. with the same start time.
## Setup
*To be typed in chat:*
<CodeHeader></CodeHeader>
```yaml
scoreboard objectives add ticks dummy
scoreboard objectives add events dummy
```
Once you have created these two objectives, you will need to define the interval for each repeating event you need on your world in the `ticks` objective.
To do that, first you must know that **1 second is approximately 20 game ticks in Minecraft**. Based on this knowledge, you will need to do some basic calculations to obtain the ticks equivalent for each interval you want to define.
<CodeHeader></CodeHeader>
```yaml
# 2h = 20(t) × 60(s) × 60(m) × 2(h) = 144000t
scoreboard players set 2h ticks 144000
#10m = 20(t) × 60(s) × 10(m) = 12000t
scoreboard players set 10m ticks 12000
#30s = 20(t) × 30(s) = 600t
scoreboard players set 30s ticks 600
```
We will now use this scoreboard data to make our timers function.
## System
<CodeHeader>mcfunction</CodeHeader>
```yaml
scoreboard players add timer ticks 1
scoreboard players operation * events = timer ticks
#Chat Message (every 2h)
scoreboard players operation chatMessage events %= 2h ticks
execute if score chatMessage events matches 0 run say Technoblade never dies!
#Lag Clear (every 10m)
scoreboard players operation lagClear events %= 10m ticks
execute if score lagClear events matches 0 run function clear_lag
#Speed Effect (every 30s)
scoreboard players operation speedEffect events %= 30s ticks
execute if score speedEffect events matches 0 run effect @a speed 10 2 true
```
![commandBlockChain8](/assets/images/commands/commandBlockChain/8.png)
Here we have taken 3 examples to give you an idea on how to do it, but you can add any timer you need and as many as you require.
Just make sure to follow the given order and properly use the `/execute if score` command as shown to run the commands you need.
## Explanation
- **` events `** on this objective we label all the repeating events we want on our world.
- `chatMessage`
- `lagClear`
- `speedEffect`
- **` ticks `** on this objective we define all the intervals for our events and also run our scoreboard timer.
- ` 2h` interval (static score 144000)
- `10m` interval (static score 12000)
- `30s` interval (static score 600)
- `timer` clock (variable score n+1)
- **Command 1:** this command adds +1 score every tick to FakePlayer name `timer` indicating a tick has passed in the game. This is basically our scoreboard timer/clock which we will use for all the repeating events on our world.
- **Command 2:** here we copy `timer` score to all our events using the ` * ` wildcard selector. This will allow us to perform operations to determine if the interval has been reached to run the commands for that particular event. Example:
- If `timer` score is 1200 that means 1200 game ticks have passed.
- And this command makes it so all our events FakePlayer names: `chatMessage`, `lagClear`, `speedEffect` scores are also 1200.
- **Command 3:** we will use the ` %= ` modulo operation to check if our event score is divisible by it's corresponding interval. A number is said to be divisible when the remainder is 0.
- Chat Message: `1200/144000` Q=0, R=1200, *hence interval not reached.*
- Lag Clear: `1200/12000` Q=0, R=1200, *hence interval not reached.*
- Speed Effect: `1200/600` Q=2, R=0, *hence interval has reached and event commands can be executed.*
Here we can note that the first 2 events are yet to happen but the 3rd event is happening for the second time.
:::tip
In Minecraft; scoreboard division is only calculated up to whole numbers and decimal values are ignored.
![longDivision](/assets/images/commands/longDivision.png)
:::
- **Command 4:** the remainder value obtained from the calculation is applied to the corresponding event FakePlayer name. Based on this knowledge we can run our command if it's score is equal to 0.
The rest of the commands are identical in structure and only the event labels and interval values are changed.
## Defining Events With Limited Intervals
To limit how many times an event occurs, you will need to create a new objective called `intervals` and define how many times the event should occur like so:
<CodeHeader></CodeHeader>
```yaml
scoreboard objectives set chatMessage intervals 5
scoreboard objectives set speedEffect intervals 10
```
Once you have done that, modify your system from above like so:
<CodeHeader>mcfunction</CodeHeader>
```yaml
scoreboard players add timer ticks 1
scoreboard players operation * events = timer ticks
#Chat Message (every 10m)
scoreboard players operation chatMessage events %= 2h ticks
execute if score chatMessage events matches 0 if score chatMessage intervals matches 1.. run say Technoblade never dies!
execute if score chatMessage events matches 0 if score chatMessage intervals matches 1.. run scoreboard players remove chatMessage intervals 1
#Speed Effect (every 30s)
scoreboard players operation speedEffect events %= 30s ticks
execute if score speedEffect events matches 0 if score speedEffect intervals matches 1.. run effect @a speed 10 2 true
execute if score speedEffect events matches 0 if score speedEffect intervals matches 1.. run scoreboard players remove speedEffect intervals 1
```
![commandBlockChain8](/assets/images/commands/commandBlockChain/8.png)
## Executing Commands During Timeframe
To run commands during the timeframe between intervals for a particular system you may do something like this:
<CodeHeader>mcfunction</CodeHeader>
```yaml
#Speed Effect (every 30s) + Particle (every tick)
scoreboard players operation speedEffect events %= 30s ticks
execute if score speedEffect intervals matches 1.. as @a at @s run particle minecraft:shulker_bullet ~~~
execute if score speedEffect events matches 0 if score speedEffect intervals matches 1.. run effect @a speed 10 2 true
execute if score speedEffect events matches 0 if score speedEffect intervals matches 1.. run scoreboard players remove speedEffect intervals 1
```
As shown in line 3; to run commands while the timer is running, all you need to do is remove the "if score" testing if the interval has been reached. And instead, only test if *any* interval is left, to run our commands.
Let's say we had set the intervals for this event to 10, then that means players would also have particle trails for 300 seconds since `10*30s=300s`
## Entity Timers
In some cases such as an entity despawn event you will need to run timers for each entity individually rather than a synchronised timer which could cause the event to trigger too soon. In such cases an Async Timer can be helpful.
Let's say we want to:
- kill all entities named "station" 5 minutes after they've been summoned.
- play a shulker particle around them during that timeframe.
- play a flame particle around them in the first 10 seconds.
- play a pling sound to nearby players when the timer reaches half way.
- stop the timer if a passive mob is nearby.
- loop the timer if a hostile mob is nearby.
<CodeHeader>mcfunction</CodeHeader>
```yaml
#Clock
scoreboard players add @e [name=station, scores={ticks=0..}] ticks 1
#Executing Commands while timer is running
execute as @e [name=station, scores={ticks=0..}] at @s run particle minecraft:shulker_bullet ~~~
#Executing commands within a timeframe
execute as @e [name=station, scores={ticks=0..200}] at @s run particle minecraft:basic_flame_particle ~~~
#Executing commands at specific intervals
execute as @e [name=station, scores={ticks=3600}] at @s run playsound note.pling @a [r=10]
#Stopping the timer
execute as @e [name=station] at @s if entity @e [family=pacified, r=10, c=1] run scoreboard players set @s ticks -1
#Looping the timer
execute as @e [name=station, scores={ticks=6000}] at @s if entity @e [family=monster, r=10, c=1] run scoreboard players set @s ticks 0
#End
kill @e [name=station, scores={ticks=6000}]
```
![commandBlockChain7](/assets/images/commands/commandBlockChain/7.png)
As shown; setting the score to 0 when it completes the timeframe will loop the timer and setting the score to -1 will stop/disable it. You can still set the score to 0 to start the timer again.

217
docs/wiki/commands/selectors.md Normal file
View File

@@ -0,0 +1,217 @@
---
title: Understanding Selectors
category: General
mentions:
- Science-geek42
- Brougud
- MedicalJewel105
- SmokeyStack
- Sprunkles137
- Hatchibombotar
---
Target selectors are used in commands to target who you want to execute a command on without explicitly setting a target, such as a player's name. A target selector is comprised of a selector variable, and optionally a list of selector arguments.
## Selector Variables
The selector variable defines the broad list of entities to select. There are six selector variables to choose from:
- `@a` - Target all players
- `@p` - Target the nearest player
- `@r` - Target a random player
- `@e` - Target all entities
- `@s` - Target the executor
- `@initiator` - Target the player interacting with an NPC
## Selector Arguments
Selector arguments can narrow down a list of target candidates to those who meet certain conditions. In order to use selector arguments, you must first have a selector variable. To start with selector arguments you must add square brackets `[]` to the end of the chosen target selector like this: `kill @e[]`. Multiple selector arguments can be used by separating them with commas.
### Type
Limits the selection of targets by their identifier. Negating the argument selects entities without that identifier. This argument cannot be repeated unless negated, since a given entity can only have one identifier. This argument can be used with the selector `@r` to select entities randomly.
- `type=<identifier>`—Include only entities with the given identifier.
- `type=!<identifier>`—Exclude any entities with the given identifier.
Examples:
Affect all pigs with levitation:
- `/effect @e[type=pig] levitation`
Kill all entities that are not arrows and snowballs:
- `/kill @e[type=!arrow,type=!snowball]`
### Count
Limits the number of selected entities, following selector sorting rules.
The selectors `@a`, `@p`, and `@e` sort by increasing distance, while `@r` sorts randomly. For the variables `@p` and `@r`, this argument defaults to 1. Negating this argument reverses the sorting order; random sorting cannot be negated.
- `c=<count>`—Select up to `<count>` entities.
Examples:
Clear stone from the closest five players:
- `/clear @a[c=5] stone`
Damage the furthest two skeletons:
- `/damage @e[type=skeleton,c=-2] 2`
### Position
Changes the position a selector starts its search at. It also modifies where the distance and volume arguments are positioned. Leaving any undefined defaults to the command's current position.
[Relative coordinates](/commands/relative-coordinates#relative-coordinates) can be used to define a relative offset from the command's position.
- `x=<value>`, `y=<value>`, and `z=<value>`—Defines a position for the target selector.
Examples:
Teleport the closest player to (140, 64, -200) ten blocks up:
- `/teleport @p[x=140, y=64, z=-200] ~ ~10 ~`
### Distance
Limits the selection of targets by their spherical distance from the selector. This selects entities by their feet.
- `rm=<value>` and `r=<value>`—Selects entities between the minimum and maximum number of blocks away, inclusive and respectively.
Examples:
Kill all chickens between two and six blocks away:
- `/kill @e[type=chicken, rm=2, r=6]`
Enchant the held item with Sharpness for all players within one block of (0, 100, 0):
- `/enchant @a[x=0, y=100, z=0, r=1] sharpness`
### Volume
Limits the selection of targets to those inside of a cuboid volume aligned to the block grid. There are three arguments, each determining the size of the box along their respective axes. If at least one argument is defined, any remaining arguments left undefined are assumed to be 0. This selects entities by their feet.
The general formula for calculating the volume between two positions can be viewed as: `dx = x2 - x1; dy = y2 - y1; dz = z2 - z1`.
- `dx=<value>`, `dy=<value>`, and `dz=<value>`—Selects entities inside the given bounding box.
Examples:
List all entities within a 12x30x2 box:
- `/say @e[dx=12, dz=30, dy=2]`
Add the "lobby" tag to all players between (-400, 0, -350) and (-150, 256, 50):
- `/tag @a[x=-400, y=0, z=-350, dx=250, dy=256, dz=400] add lobby`
### Scores
Limits the selection of targets by their score value. This argument is represented as an object, with key-value pairs for a scoreboard objective and a value. The value can represent a range of numbers, using the range syntax. The value of a score can be negated to test if the entity does not have a score value within that range.
- `scores={<objective>=<value>}`—Selects entities whose score under the given objective matches the given value.
The range syntax works as follows:
- `N..` is any number greater than or equal to N.
- `..N` is any number less than or equal to N.
- `N..M` is any number between N and M, inclusive.
Examples:
Set the "points" score for all players with a "points" score of ten to 0:
- `/scoreboard players set @p[scores={points=10}] points 0`
Add the "start" tag to armor stands with both a "started" score of one, and a "timer" score of 20 or less:
- `/tag @e[type=armor_stand, scores={started=1, timer=..20}] add start`
### Name
Limits the selection of targets by name. Negating the argument selects entities whose name does not match.
- `name=<name>`—Include only entities with the given name.
- `name=!<name>`—Exclude any entities with the given name.
Examples:
List all zombies named Shadow:
- `/say @e[type=zombie, name=Shadow]`
Give one level to players both not named Steve and not named Alex:
- `/xp 1L @a[name=!Steve, name=!Alex]`
### Tag
Limits the selection of targets by their tags. This argument can be repeated to test for multiple tags, and all filters must pass for an entity to be selected. Negating this argument selects entities without that tag.
- `tag=<tag>`—Include only entities with the given tag.
- `tag=!<tag>`—Exclude any entities with the given tag.
Examples:
Kill all mobs with the tag "marked", and without the tag "exempt":
- `/kill @e[tag=marked, tag=!exempt]`
### Family
Limits the selection of targets by type family. This argument can be repeated to test for multiple families, and all filters must pass for an entity to be selected. Negating this argument selects entities whose type family does not match.
- `family=<family>`—Include only entities with the given type family.
- `family=!<family>`—Exclude any entities with the given type family.
Examples:
Affect all entities in the "monster" family with Regeneration:
- `/effect @e[family=monster] regeneration`
### Rotation
Limits the selection of targets by their rotation. There are two types of rotation: x-rotation, which is vertical rotation around the x-axis; and y-rotation, which is horizontal rotation around the y-axis. X-rotation ranges between -90 and 90 (180° total), going from looking up to down; and y-rotation ranges between -180 and 180 (360° total), starting and ending at North, wrapping around clockwise.
- `rxm=<value>` and `rx=<value>`—Selects entities whose x-rotation is between the minimum and maximum values, inclusive and respectively.
- `rym=<value>` and `ry=<value>`—Selects entities whose y-rotation is between the minimum and maximum values, inclusive and respectively.
Examples:
Affect all players looking at or above the horizon with Blindness for one second:
- `/effect @a[rx=0] blindness 1` (0 or less)
Damage all players facing generally south:
- `/damage @a[rym=-45, ry=45] 1`
### Level
Limits the selection of targets by experience levels. Only players can have EXP, so this filters out non-player targets.
- `lm=<amount>` and `l=<amount>`—Selects players whose EXP levels are between the minimum and maximum values specified, inclusive and respectively.
Examples:
Give all players who have between three and eight levels a diamond:
- `/give @a[lm=3, l=8] diamond`
### Game mode
Limits the selection of targets by game mode. Only players can use game mode, so this filters out non-player targets. Negating the argument selects targets whose game mode does not match.
- `m=<gamemode>`—Selects players by their game mode.
Possible values include:
* `0`, `s`, or `survival` for Survival mode
* `1`, `c`, or `creative` for Creative mode
* `2`, `a`, or `adventure` for Adventure mode
* `spectator` for Spectator mode
* `d` or `default` for the default game mode
Examples:
List all players in Creative mode:
- `/say @a[m=creative]`
Set the game mode to Creative mode for players both not in Survival mode, and not in Adventure mode:
- `/gamemode creative @a[m=!survival, m=!adventure]`
### Items
Limits the selection of targets by what items they have in their inventory. This argument is represented as an object, or an array of objects, with up to one each of the following parameters:
- `item=<string>`—The identifier of the item to test for, and the only required argument. This can accept custom identifiers too.
- `quantity=<int>`—The amount of the item to test for. Accepts a [range](/commands/selectors#scores) for a value. This argument can also be negated.
- `data=<int>`—The data value of the item to test for. Defaults to -1. **Currently not functional:** [MCPE-151920](https://bugs.mojang.com/browse/MCPE-151920)
- `location=<string>`—The slot the item should be located in. Accepts the same arguments as the slotType argument in the `/replaceitem` command.
- `slot=<int>`—The index of the slot used in the "location" argument, and can only be used with "location". Accepts a range for a value. This argument can be negated.
Examples:
Checks for players who have a netherite sword in their inventory:
- `/testfor @a[hasitem={item=netherite_sword}]`
Clears 2 apples for players that have four or more apples:
- `/clear @a[hasitem={item=apple,quantity=4..}] apple 2`
Checks for players who have two sticks and two diamonds:
- `/testfor @a[hasitem=[{item=diamond,quantity=2},{item=stick,quantity=2}]]`
Checks for players who doesn't have a stick:
- `/testfor @a[hasitem=[{item=stick,quantity=0}]`

132
docs/wiki/commands/tellraw.md Normal file
View File

@@ -0,0 +1,132 @@
---
title: Tellraw
category: Commands
mentions:
- SirLich
- Dreamedc2015
- MedicalJewel105
- Luthorius
- Fabrimat
- Sprunkles137
- ThomasOrs
- zheaEvyline
- SmokeyStack
---
tellraw sends a JSON message to selected or all players being useful for sending plain messages to players ingame
**The titleraw command follows the same theme**
![](/assets/images/documentation/tellrawshow.png)
## Format
this is how the tell raw command is formatted
```
tellraw <target: target> <raw json message: json>
```
- ` <target: target>`: The target is expressed as a playername or player groups such as `@a` `@r` `@s` `@p`
- `<raw json message: json>`: This is a json schema that tells how the message is structured or constructed. expressed with for example:
`{"rawtext":[{"text":""}]}`
## Examples
This sends the words in the last set of quotes
<CodeHeader></CodeHeader>
```json
/tellraw @a {"rawtext":[{"text":"Hello"}]}
```
## Escaping Characters
To use quotations in a tellraw message place a backslash to the left side of the quotation mark.
<CodeHeader></CodeHeader>
```json
/tellraw @a {"rawtext":[{"text":"Quote me: \"I am here\"."}]}
```
## Line breaks
To insert a line break use `\n`
<CodeHeader></CodeHeader>
```json
/tellraw @a { "rawtext": [ { "text":"I am line one\nI am line two" } ] }
```
## Displaying entities / player
You can use the following to use selector to display names.
<CodeHeader></CodeHeader>
```json
/tellraw @a {"rawtext": [{"text": "§6The winner is: §a"}, {"selector": "@a[r=5,c=1]"}]}
```
## Displaying scores
You can use the following to use selector to display names.
<CodeHeader></CodeHeader>
```json
/tellraw @a {"rawtext": [{"text": "§6The winner is: §a"}, {"selector": "@a[r=5,c=1]"}, {"text": "§6With a score of: "}, {"score":{"name": "@s","objective": "value"}}]}
```
## Translate text
To have a language dependant text you can use the translate component and [translation keys](/concepts/text-and-translations). please note you will need relevant information in each of the desired .lang files for this to work.
<CodeHeader>RP/texts/en_US.lang</CodeHeader>
```
example.langcode.1=I am line one
```
<CodeHeader>RP/texts/de_DE.lang</CodeHeader>
```
example.langcode.1=Ich bin Zeile eins
```
The command:
<CodeHeader></CodeHeader>
```json
/tellraw @a { "rawtext": [ { "translate": "example.langcode.1" } ] }
```
## Translate text with selectors/scores
language files:
<CodeHeader></CodeHeader>
```
example.langcode.2=The winner is: %s. With a score of %s
```
<CodeHeader></CodeHeader>
```json
/tellraw @a {"rawtext":[{"translate":"example.langcode.2","with":{"rawtext":[{"selector":"@a[r=5,c=1]"},{"text":"§6With a score of: "},{"score":{"name":"@s","objective":"value"}}]}}]}
```

84
docs/wiki/concepts/contents.md Normal file
View File

@@ -0,0 +1,84 @@
---
title: contents.json
mentions:
- MedicalJewel105
- Osaxely
- SirLich
- solvedDev
- Joelant05
- Jorginhor
- TheItsNameless
---
`contents.json` is a file that is _probably_ used for the game to process the pack files more easily. It is _probably_ intended for marketplace content creators and Mojang, it is not required to have this file in the pack for the pack to work properly.
You will find there some instructions about the usage of this file.
## Structure of the file
`contents.json` is located at the root of the add-on directory. It contains a list of the files that are included in the pack.
Example:
<CodeHeader>RP/contents.json</CodeHeader>
```json
{
"content": [
{
"path": "texts/en_US.lang"
},
{
"path": "contents.json"
},
{
"path": "manifest.json"
},
{
"path": "animations/my_animation.animation.json"
},
{
"path": "animation_controllers/my_ac.ac.json"
},
{
"path": "entity/my_entity.entity.json"
},
{
"path": "textures/textures_list.json"
},
{
"path": "textures/blocks/my_block.png"
}
]
}
```
<FolderView
:paths="[
'RP/texts/en_US.lang',
'RP/manifest.json',
'RP/contents.json',
'RP/animations/my_animation.animation.json',
'RP/animation_controllers/my_ac.ac.json',
'RP/entity/my_entity.entity.json',
'RP/textures/texture_list.json',
'RP/textures/blocks/my_block.png'
]"
> </FolderView>
## Automatizing the process
The `contents.json` file can be generated automatically by the game itself, it is very recommended to decrease the risks of making mistakes. However, the file must be prepared first. Create a new empty file called `contents.json` in the root directory of your add-on, and add empty brackets.
<CodeHeader>BP|RP/contents.json</CodeHeader>
```json
{}
```
The file content will be automatically written next time the game is launched.
## Additional information
- The automatic process can be achieved no matter what is the location of the pack (Development folders or normal folders).
- Do not make multiple `contents.json` for subpacks, the file at the root of the pack is sufficient.
- This file is not required for the addon to work properly.

289
docs/wiki/concepts/emojis.md Normal file
View File

@@ -0,0 +1,289 @@
---
title: Emojis & Symbols
mentions:
- SirLich
- Joelant05
- sovledDev
- stirante
- Dreamedc2015
- MedicalJewel105
- JaylyDev
- RealBashy21
- ColinTimBarndt
- Citicx
- TheItsNameless
- ThomasOrs
---
:::warning
Modifying texture of vanilla emojis and symbols on this page are incompatible with Nintendo Switch platform!
:::
Minecraft has a bunch of hard-coded [Private Use Unicode symbols](https://en.wikipedia.org/wiki/Private_Use_Areas) that it automatically converts to Emoji-like symbols.
These can be used anywhere where normal letters can - signs, books, item names, chat, etc.
Below you can find platform specific Emoji's, as well as general symbols. Copy/paste the "box" character under the Letter colum directly into Minecraft.
There will be instructions for creating custom emoji at the bottom.
### HUD
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ----------------- | ------------------------ | ------- | ------------------------------------------------- |
| Food |  | U+E100 | ![](/assets/images/concepts/emojis/hud/food.png) |
| Armor |  | U+E101 | ![](/assets/images/concepts/emojis/hud/armor.png) |
| Heart |  | U+E10C | ![](/assets/images/concepts/emojis/hud/heart.png) |
### Items & Blocks
| Name | Letter (Copy/Paste This) | Unicode | Image |
| -------------- | ------------------------ | ------- | ------------------------------------------------------------ |
| Wooden Pickaxe |  | U+E108 | ![](/assets/images/concepts/emojis/items/wooden_pickaxe.png) |
| Wooden Sword |  | U+E109 | ![](/assets/images/concepts/emojis/items/wooden_sword.png) |
| Crafting Table |  | U+E10A | ![](/assets/images/concepts/emojis/items/crafting_table.png) |
| Furnace |  | U+E10B | ![](/assets/images/concepts/emojis/items/furnace.png) |
### Marketplace
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ---------------- | ------------------------ | ------- | ------------------------------------------------------------ |
| Minecoin |  | U+E102 | ![](/assets/images/concepts/emojis/marketplace/minecoin.png) |
| Token |  | U+E105 | ![](/assets/images/concepts/emojis/marketplace/token.png) |
### Inventory
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ---------------- | ------------------------ | ------- | ------------------------------------------------------------------ |
| Craft Toggle On |  | U+E0A0 | ![](/assets/images/concepts/emojis/inventory/craft_toggle_on.png) |
| Craft Toggle Off |  | U+E0A1 | ![](/assets/images/concepts/emojis/inventory/craft_toggle_off.png) |
### New Touch
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ----------------- | ------------------------ | ------- | ---------------------------------------------------------- |
| Jump |  | U+E014 | ![](/assets/images/concepts/emojis/new_touch/jump.png) |
| Attack |  | U+E015 | ![](/assets/images/concepts/emojis/new_touch/attack.png) |
| Joy Stick |  | U+E016 | ![](/assets/images/concepts/emojis/new_touch/joystick.png) |
| Place |  | U+E018 | ![](/assets/images/concepts/emojis/new_touch/place.png) |
| Sneak |  | U+E019 | ![](/assets/images/concepts/emojis/new_touch/sneak.png) |
| Sprint |  | U+E01A | ![](/assets/images/concepts/emojis/new_touch/sprint.png) |
| Fly Up |  | U+E01B | ![](/assets/images/concepts/emojis/new_touch/fly_up.png) |
| Fly Down |  | U+E01C | ![](/assets/images/concepts/emojis/new_touch/fly_down.png) |
| Dismount |  | U+E01D | ![](/assets/images/concepts/emojis/new_touch/dismount.png) |
### Touch
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ----------------- | ------------------------ | ------- | ------------------------------------------------------------- |
| Jump |  | U+E084 | ![](/assets/images/concepts/emojis/touch/jump.png) |
| Crouch |  | U+E085 | ![](/assets/images/concepts/emojis/touch/crouch.png) |
| Fly Up |  | U+E086 | ![](/assets/images/concepts/emojis/touch/fly_up.png) |
| Fly Down |  | U+E087 | ![](/assets/images/concepts/emojis/touch/fly_down.png) |
| Stop Flying |  | U+E088 | ![](/assets/images/concepts/emojis/touch/stop_flying.png) |
| Left Arrow |  | U+E081 | ![](/assets/images/concepts/emojis/touch/left_arrow.png) |
| Right Arrow |  | U+E083 | ![](/assets/images/concepts/emojis/touch/right_arrow.png) |
| Up Arrow |  | U+E080 | ![](/assets/images/concepts/emojis/touch/up_arrow.png) |
| Down Arrow |  | U+E082 | ![](/assets/images/concepts/emojis/touch/down_arrow.png) |
| Small Jump |  | U+E059 | ![](/assets/images/concepts/emojis/touch/smalljump.png) |
| Small Crouch |  | U+E05A | ![](/assets/images/concepts/emojis/touch/smallcrouch.png) |
| Small Fly Up |  | U+E05C | ![](/assets/images/concepts/emojis/touch/smallflyup.png) |
| Small Fly Down |  | U+E05D | ![](/assets/images/concepts/emojis/touch/smallflydown.png) |
| Small Left Arrow |  | U+E056 | ![](/assets/images/concepts/emojis/touch/smallleftarrow.png) |
| Small Right Arrow |  | U+E058 | ![](/assets/images/concepts/emojis/touch/smallrightarrow.png) |
| Small Up Arrow |  | U+E055 | ![](/assets/images/concepts/emojis/touch/smalluparrow.png) |
| Small Down Arrow |  | U+E057 | ![](/assets/images/concepts/emojis/touch/smalldownarrow.png) |
| Small Inventory |  | U+E05B | ![](/assets/images/concepts/emojis/touch/smallinventory.png) |
### Keyboard & Mouse
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ------------------ | ------------------------ | ------- | ------------------------------------------------------------------- |
| Left Click |  | U+E060 | ![](/assets/images/concepts/emojis/keyboard/left_click.png) |
| Right Click |  | U+E061 | ![](/assets/images/concepts/emojis/keyboard/right_click.png) |
| Middle Click |  | U+E062 | ![](/assets/images/concepts/emojis/keyboard/middle_click.png) |
| Small Left Click |  | U+E070 | ![](/assets/images/concepts/emojis/keyboard/small_left_click.png) |
| Small Right Click |  | U+E071 | ![](/assets/images/concepts/emojis/keyboard/small_right_click.png) |
| Small Middle Click |  | U+E072 | ![](/assets/images/concepts/emojis/keyboard/small_middle_click.png) |
| Small Mouse |  | U+E073 | ![](/assets/images/concepts/emojis/keyboard/small_mouse.png) |
### Xbox
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ------------------ | ------------------------ | ------- | ---------------------------------------------------------- |
| Y |  | U+E003 | ![](/assets/images/concepts/emojis/xbox/y_button.png) |
| B |  | U+E001 | ![](/assets/images/concepts/emojis/xbox/b_button.png) |
| A |  | U+E000 | ![](/assets/images/concepts/emojis/xbox/a_button.png) |
| X |  | U+E002 | ![](/assets/images/concepts/emojis/xbox/x_button.png) |
| Back |  | U+E008 | ![](/assets/images/concepts/emojis/xbox/back.png) |
| Start |  | U+E009 | ![](/assets/images/concepts/emojis/xbox/start.png) |
| LB (Left Bumper) |  | U+E004 | ![](/assets/images/concepts/emojis/xbox/left_bumper.png) |
| RB (Right Bumper) |  | U+E005 | ![](/assets/images/concepts/emojis/xbox/right_bumper.png) |
| LT (Left Trigger) |  | U+E006 | ![](/assets/images/concepts/emojis/xbox/left_trigger.png) |
| RT (Right Trigger) |  | U+E007 | ![](/assets/images/concepts/emojis/xbox/right_trigger.png) |
| LS (Left Stick) |  | U+E00A | ![](/assets/images/concepts/emojis/xbox/left_stick.png) |
| RS (Right Stick) |  | U+E00B | ![](/assets/images/concepts/emojis/xbox/right_stick.png) |
| D-pad Up |  | U+E00C | ![](/assets/images/concepts/emojis/xbox/dpad_up.png) |
| D-pad Right |  | U+E00F | ![](/assets/images/concepts/emojis/xbox/dpad_right.png) |
| D-pad Down |  | U+E00E | ![](/assets/images/concepts/emojis/xbox/dpad_down.png) |
| D-pad Left |  | U+E00D | ![](/assets/images/concepts/emojis/xbox/dpad_left.png) |
### Nintendo Switch
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ------------------ | ------------------------ | ------- | ------------------------------------------------------------ |
| X |  | U+E042 | ![](/assets/images/concepts/emojis/switch/x_button.png) |
| A |  | U+E040 | ![](/assets/images/concepts/emojis/switch/a_button.png) |
| B |  | U+E041 | ![](/assets/images/concepts/emojis/switch/b_button.png) |
| Y |  | U+E043 | ![](/assets/images/concepts/emojis/switch/y_button.png) |
| + |  | U+E049 | ![](/assets/images/concepts/emojis/switch/plus.png) |
| - |  | U+E048 | ![](/assets/images/concepts/emojis/switch/minus.png) |
| L (Left Bumper) |  | U+E044 | ![](/assets/images/concepts/emojis/switch/left_bumper.png) |
| R (Right Bumper) |  | U+E045 | ![](/assets/images/concepts/emojis/switch/right_bumper.png) |
| ZL (Left Trigger) |  | U+E046 | ![](/assets/images/concepts/emojis/switch/left_trigger.png) |
| RL (Right Trigger) |  | U+E047 | ![](/assets/images/concepts/emojis/switch/right_trigger.png) |
| L (Left Stick) |  | U+E04A | ![](/assets/images/concepts/emojis/switch/left_stick.png) |
| R (Right Stick) |  | U+E04B | ![](/assets/images/concepts/emojis/switch/right_stick.png) |
| D-pad Up |  | U+E04C | ![](/assets/images/concepts/emojis/switch/dpad_up.png) |
| D-pad Right |  | U+E04F | ![](/assets/images/concepts/emojis/switch/dpad_right.png) |
| D-pad Down |  | U+E04E | ![](/assets/images/concepts/emojis/switch/dpad_down.png) |
| D-pad Left |  | U+E04D | ![](/assets/images/concepts/emojis/switch/dpad_left.png) |
### PlayStation (4/5)
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ------------------ | ------------------------ | ------- | ----------------------------------------------------------------- |
| Triangle |  | U+E023 | ![](/assets/images/concepts/emojis/playstation/triangle.png) |
| Circle |  | U+E021 | ![](/assets/images/concepts/emojis/playstation/circle.png) |
| Cross |  | U+E020 | ![](/assets/images/concepts/emojis/playstation/cross.png) |
| Square |  | U+E022 | ![](/assets/images/concepts/emojis/playstation/square.png) |
| Options/Share |  | U+E029 | ![](/assets/images/concepts/emojis/playstation/options_share.png) |
| Touch Pad |  | U+E028 | ![](/assets/images/concepts/emojis/playstation/touch_pad.png) |
| L1 (Left Bumper) |  | U+E024 | ![](/assets/images/concepts/emojis/playstation/left_bumper.png) |
| R1 (Right Bumper) |  | U+E025 | ![](/assets/images/concepts/emojis/playstation/right_bumper.png) |
| L2 (Left Trigger) |  | U+E026 | ![](/assets/images/concepts/emojis/playstation/left_trigger.png) |
| R2 (Right Trigger) |  | U+E027 | ![](/assets/images/concepts/emojis/playstation/right_trigger.png) |
| L3 (Left Stick) |  | U+E02A | ![](/assets/images/concepts/emojis/playstation/left_stick.png) |
| R3 (Right Stick) |  | U+E02B | ![](/assets/images/concepts/emojis/playstation/right_stick.png) |
| D-pad Up |  | U+E02C | ![](/assets/images/concepts/emojis/playstation/dpad_up.png) |
| D-pad Right |  | U+E02F | ![](/assets/images/concepts/emojis/playstation/dpad_right.png) |
| D-pad Down |  | U+E02E | ![](/assets/images/concepts/emojis/playstation/dpad_down.png) |
| D-pad Left |  | U+E02D | ![](/assets/images/concepts/emojis/playstation/dpad_left.png) |
### Oculus (Rift/Rift S)
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ------------------ | ------------------------ | ------- | ------------------------------------------------------------ |
| 0 |  | U+E0E0 | ![](/assets/images/concepts/emojis/oculus/0_button.png) |
| B |  | U+E0E2 | ![](/assets/images/concepts/emojis/oculus/b_button.png) |
| A |  | U+E0E1 | ![](/assets/images/concepts/emojis/oculus/a_button.png) |
| Y |  | U+E0EA | ![](/assets/images/concepts/emojis/oculus/y_button.png) |
| X |  | U+E0E9 | ![](/assets/images/concepts/emojis/oculus/x_button.png) |
| LG (Left Grip) |  | U+E0E3 | ![](/assets/images/concepts/emojis/oculus/left_grip.png) |
| RG (Right Grip) |  | U+E0E4 | ![](/assets/images/concepts/emojis/oculus/right_grip.png) |
| LT (Left Trigger) |  | U+E0E7 | ![](/assets/images/concepts/emojis/oculus/left_trigger.png) |
| RT (Right Trigger) |  | U+E0E8 | ![](/assets/images/concepts/emojis/oculus/right_trigger.png) |
| LS (Left Stick) |  | U+E0E5 | ![](/assets/images/concepts/emojis/oculus/left_stick.png) |
| RS (Right Stick) |  | U+E0E6 | ![](/assets/images/concepts/emojis/oculus/right_stick.png) |
### Windows MR (Mixed Reality)
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ------------------------- | ------------------------ | ------- | --------------------------------------------------------------------------- |
| Menu |  | U+E0C2 | ![](/assets/images/concepts/emojis/windowsMR/menu.png) |
| Windows |  | U+E0CD | ![](/assets/images/concepts/emojis/windowsMR/windows.png) |
| Left Touchpad |  | U+E0C5 | ![](/assets/images/concepts/emojis/windowsMR/left_touchpad.png) |
| Left Horizontal Touchpad |  | U+E0C6 | ![](/assets/images/concepts/emojis/windowsMR/left_touchpad_horizontal.png) |
| Left Vertical Touchpad |  | U+E0C7 | ![](/assets/images/concepts/emojis/windowsMR/left_touchpad_vertical.png) |
| Right Touchpad |  | U+E0C8 | ![](/assets/images/concepts/emojis/windowsMR/right_touchpad.png) |
| Right Horizontal Touchpad |  | U+E0C9 | ![](/assets/images/concepts/emojis/windowsMR/right_touchpad_horizontal.png) |
| Right Vertical Touchpad |  | U+E0CA | ![](/assets/images/concepts/emojis/windowsMR/right_touchpad_vertical.png) |
| LT (Left Trigger) |  | U+E0CB | ![](/assets/images/concepts/emojis/windowsMR/left_trigger.png) |
| RT (Right Trigger) |  | U+E0CC | ![](/assets/images/concepts/emojis/windowsMR/right_trigger.png) |
| LG (Left Grab) |  | U+E0C0 | ![](/assets/images/concepts/emojis/windowsMR/left_grab.png) |
| RG (Right Grab) |  | U+E0C1 | ![](/assets/images/concepts/emojis/windowsMR/right_grab.png) |
| LS (Left Stick) |  | U+E0C3 | ![](/assets/images/concepts/emojis/windowsMR/left_stick.png) |
| RS (Right Stick) |  | U+E0C4 | ![](/assets/images/concepts/emojis/windowsMR/right_stick.png) |
### Other
| Name | Letter (Copy/Paste This) | Unicode | Image |
| ---------------- | ------------------------ | ------- | -------------------------------------------------------------- |
| Crosshair |  | U+E017 | ![](/assets/images/concepts/emojis/other/crosshair.png) |
| Agent |  | U+E103 | ![](/assets/images/concepts/emojis/other/agent.png) |
| Immersive Reader |  | U+E104 | ![](/assets/images/concepts/emojis/other/immersive_reader.png) |
| Hollow Star |  | U+E106 | ![](/assets/images/concepts/emojis/other/hollow_star.png) |
| Solid Star |  | U+E107 | ![](/assets/images/concepts/emojis/other/solid_star.png) |
## Custom Emoji
::: warning
This method is not officially supported. Use with caution on the Marketplace!
:::
To make a custom emoji, we use a very similar method to the pre-built emoji, except instead of using the Microsoft sprite-sheets, we overwrite them with our own! Some _character-slots_ are already used up with the emoji above, but there are blank slots we can use.
Please note that the following files have been annotated with slot information: If you use them directly, existing Emoji will have numbers added on top of them. If you need the original sprite-sheets, you can get them from the Vanilla Resources on your system (not included in the Vanilla Resource Pack downloads).
To get started, you should download the sprite-sheets, and move them into the fonts folder.
Two sprite-sheets are provided for each glyph-target: One that accurately reflects vanilla, and a second version which has been annotated with hex information, for easily finding the correct character.
### RP/font/glyph_E0.png
![](/assets/images/concepts/emojis/custom/annotated/glyph_E0.png)
![](/assets/images/concepts/emojis/custom/glyph_E0.png)
### RP/font/glyph_E1.png
![](/assets/images/concepts/emojis/custom/annotated/glyph_E1.png)
![](/assets/images/concepts/emojis/custom/glyph_E1.png)
Your filepath should look like this:
<FolderView
:paths="[
'RP',
'RP/font',
'RP/font/glyph_E0.png',
'RP/font/glyph_E1.png'
]"
></FolderView>
### Finding the correct hex.
Once you have emojis inside the `glyph_E0.png` or `glyph_E1.png` you need to find your character "code" so it can be converted.
The first two characters are always `0x`.
The next two characters are either `E0` or `E1`, depending on which file you added emojis to.
The next two characters are the position inside the image like `<row><column>`, where each character is a number in hexadecimal numeral system. You can find this number by referencing the images above. For example, the top-right square in `E0` is `0F`, and the bottom right is `FF`.
So after you are done, it might look like `0xE102` (`0x` + `E1` + `02`).
Copy this code into the following field, and press <kbd>Convert</kbd>. The symbol on the right-hand side can be copy/pasted into MC.
<div markdown="0">
<form>
<input id="hexValue" placeholder="Hex value" style="padding: 1em;margin: 0.5em;border-radius: 0.4rem; border: solid 1px rgb(38, 38, 38); outline: none;color: blue;"/>
<input id="result" placeholder="Result" readonly style="padding: 1em;margin: 0.5em;border-radius: 0.4rem; border: solid 1px rgb(38, 38, 38); outline: none;color: blue;"/>
<a onclick="document.getElementById('result').value = String.fromCodePoint(parseInt(document.getElementById('hexValue').value, 16))" style="text-decoration: none; color: white; background: rgb(91, 33, 182); padding: 0.5em; border-radius: 0.4em; cursor: pointer;">Convert</a>
</form>
</div>
### Glyph Separation Space
Sometimes, it appears that if you put 2 glyphs near to each other, there will be a couple of empty pixels between them. The only fix for it is to scale the glyph itself.

3
docs/wiki/concepts/index.md Normal file
View File

@@ -0,0 +1,3 @@
---
title: Concepts
---

47
docs/wiki/concepts/molang.md Normal file
View File

@@ -0,0 +1,47 @@
---
title: Molang
tags:
- intermediate
mentions:
- yanasakana
- TheDoctor15
- MedicalJewel105
- DoubleShotgun
- Luthorius
- TheItsNameless
---
## Introduction
Pretty much everything evaluates to a number; if something doesn't evaluate to a number, you can use an `operator` to make it into one. You can basically just think of Molang as one big math equation.
An equation evaluates to `true` when any number except `0` is returned. When I reference `returning`, I'm talking about the output of an equation. There is also a `return` statement, but I don't usually use it, and will therefore not be talking about it.
## Accessing Values
There are three main ways to access and use values in Molang (queries, variables and temp variables)
- **Queries** are read only values returned by the game. You cannot set these values, only read them. (`query.example_query` | `q.example_query`)
- **Variables** are read and write values that you can manipulate, these can be set and read through Molang. (`variable.example_variable` | `v.example_variable`)
- There are also hard-coded variables which act practically the same way as queries, but can only be used in certain situations.
- **Temp. Variables** are practically the same as variables, except they only exist in the current scope. (`temp.example_temp` | `t.example_temp`)
- A "scope" can refer to the current `for_each` or `loop` *or* just the current expression, if it's not used within either
## Handling values
- **Logical Operators** can be used to convert non-numbers into 1s or 0s. These include: `==`, `!=`, `<`, `>`, `<=`, `>=`.
- Example.) "`q.get_equipped_item_name == 'stick'`" Will evaluate to `1`/`true` when holding a stick
- There is also a *second* set of *Logical Operators* which can be used to 'group' values into `and/or` statements, often used in cases where you need *multiple* things to evaluate to `true` or just *one out of many*. `&&` represents an `and` statement, and `||` represents an `or` statement.
- Example.) "`q.is_sneaking && q.is_using_item`" Will evaluate to `1`/`true` when sneaking *and* using an item
- Example.) "`q.is_sneaking || q.is_jumping`" // Evaluates to `1`/`true` when either jumping *or* sneaking
- **Parentheses**, `( )`, are also a major help when grouping values or performing math operations.
- Example.) "`q.is_sneaking && (q.get_equipped_item_name == "stick" || q.get_equipped_item_name == "diamond")`" Will evaluate to `1`/`true` when sneaking *and* holding either a stick *or* a diamond
- **Conditional Operators** can be used as `if/else` statements.
- A *binary* conditional operator refers to just using `?`. When this is used, it'll output your value or `0` depending on whether the given input value is `true`.
- Example.) "`q.is_sneaking ? 5`" Will output a `5` when sneaking, otherwise returning a `0`
- A *trinary* conditional operator refers to using `?` and `:`. When this is used, it'll output one of the two given values depending on whether your given input value is `true`.
- Example.) "`q.is_sneaking ? 10 : 3`" Will output a `10` when sneaking, otherwise returning a `3`

51
docs/wiki/concepts/namespaces.md Normal file
View File

@@ -0,0 +1,51 @@
---
title: Namespaces
mentions:
- SirLich
- MedicalJewel105
---
Namespaces are identifiers that mark content ownership. You can think of them as folders. Namespaces are helpful because they keep naming conflicts from happening.
Namespaces in addon creation can essentially be thought of as "the part to the left of the colon". For example, `minecraft` is the namespace of `minecraft:zombie`. The general form is `namespace:name`.
As a concrete example of why namespaces are helpful, let's imagine you create a new Mob. You name it `minecraft:shark`, not aware that you should create your own namespace for custom content. Next year, Mojang decides to add sharks into the game! Now there is a naming conflict since there are two definitions of `minecraft:shark`. Your addon will break.
If you had instead used `your_namespace:shark`, the naming conflict wouldn't have happened.
## Picking a namespace
A suitable namespace is unique to you. Something like `mob` or `cars` or `content` or `custom` would be a **bad** namespace since another developer might come up with the same namespace as you.
A suitable namespace is short. You will be writing your namespace a **LOT**, so the shorter, the better. `george_carlin_the_comedian` would be a lousy namespace for this reason.
For personal projects, I recommend a convenient version of your player name, and for commercial projects, I recommend a suitable version of the company name.
Some good examples:
- `gcarlin`
- `sirlich`
- `cubeworld`
- `bworks`
**DO NOT USE** `minecraft` or `minecon` as a namespace unless editing a vanilla file. Not only is it a terrible idea, but Minecraft reserves these, and it won't even work.
## Where to use namespaces?
In short, you should use namespaces as often as you can.
For starters, you should use a namespace when adding custom entities to the game.
`sirlich:shark` is much better than `shark`.
It would be best if you also used namespaces for components and events. Just like Mojang uses `minecraft:pig_saddled` you should use `namespace:my_mob_event`, and `namespace:my_component_group`.
It would be best if you also used namespaces in animation controllers, render controllers, and animations.
For example: `controller.animation.namespace.entity_name.action` is better than `controller.animation.my_action`.
## Where NOT to use namespaces.
The actual file structure does not need namespaces.
`animations/namespace/my_entity/animation` is more confusing than `animations/my_entity/animation`.

120
docs/wiki/concepts/overwriting-assets.md Normal file
View File

@@ -0,0 +1,120 @@
---
title: Overwriting Assets
tags:
- intermediate
mentions:
- SirLich
- MedicalJewel105
- Luthorius
- SmokeyStack
---
## Addon Layering
The addon system is built layer by layer, where each pack is added _on top_ of the ones before it. Even if you only have a single pack added, there is an implicit _vanilla_ pack which is always added. When you add custom content, this content will have full access to all vanilla files.
### Accessing Vanilla Files
This layered structure is very useful, because it allows us to access the files inside of vanilla, without copy/pasting them into our addon. For example you can access `blocks/stone.png` without moving it into your addon! Just set it as the texture for your custom entity - it will work out of the box. This is particularly useful for things like models, or render controllers, or sounds.
If the vanilla assets change, for example if [JAPPA](https://twitter.com/JasperBoerstra?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor) updates the stone texture, your addon will also receive the update, since you are relying on the actual dynamic, vanilla resources.
You should try to use this system of layering as often as you can. If you don't *need* to copy/paste something into your addon, don't.
:::warning
It is never OK to make an addon inside of a copy of the vanilla resource/behavior pack. This will make the download for your addon incredibly huge, and will reduce performance. Always begin with a blank addon, then copy/paste the files you want to overwrite.
:::
## Overwriting Assets
Pack Layering also allows us to overwrite vanilla assets, by _overwriting_ them with a file that shares the same path, or the same identifier. Our new file will replace the one being used in vanilla, allowing us to change textures, sounds, entity behavior, etc.
:::warning
Different resources have different methods of overwriting, so be careful to use the right method for each type!
:::
### Overwriting by Path
Assets that are referenced by _path_, and do _not have an identifier_ can be overwritten by simply placing a new asset into the same path. The following can be overwritten in this way:
- Functions
- Loot tables
- Textures
- Sounds
- Trade Tables
When you overwrite these files, the overwriting is absolute: The new asset will fully replace the old asset.
:::tip
**Example**: If you would like to replace the redstone ore texture, simply place a new file at `textures/blocks/redstone_ore.png`.
:::
### Overwriting by Identifier
Many assets are defined not by their name, but by their identifier! To overwrite these assets, simply create a new file that shares the same identifier, regardless of file-path. The following can be overwritten in this way:
- BP Entities
- RP Entities
- Animations
- Models
- Animation Controllers
- Spawn Rules
- Recipes
- Particles
- Render Controllers
When you overwrite these files, the overwriting is absolute: The new asset will fully replace the old asset.
:::tip
**Example**: If you would like to make Ghasts have higher health, simply create a new BP entity with the `minecraft:ghast` identifier, and all the behaviors required to make the ghast function.
Remember, entity files do not merge together, so you will first need to copy/paste the entire BP Ghast file, and _then_ edit the health. Simply creating a `minecraft:ghast` with a high health component inside will not work.
:::
### Overwriting via Reference File
Many assets can also be registered into some kind of "registration system" file. These files are interesting, because unlike the other asset types, they are _merged together_ instead of _overwritten_. This means that when you define these files, you do not need to copy from the vanilla resources. You can simply start with a blank file, and then overwrite the specific definitions you want.
The following files work in this way:
- All UI files
- [All language files](/concepts/text-and-translations)
- `item_textures.json`
- `flipbook_textures.json`
- `terrain_textures.json`
- `sounds.json`
- `music_definitions.json`
- `sound_definitions.json`
:::tip
**Example:** Lets say you want to override the `sugar` texture, using the reference files. You can do so by creating a new `item_textures.json`, with the following contents:
<CodeHeader></CodeHeader>
```json
{
"resource_pack_name": "vanilla",
"texture_data": {
"sugar": {
"textures": "textures/path/to/my/sugar"
}
}
}
```
This _definition_ will be merged with the vanilla `item_textures.json`, and will override the short-name `sugar`. When the vanilla item accesses this short-name, it will get a reference to your custom texture path, instead of the actual texture path to sugar.
:::
## Overwriting Dangers
Since addons mostly _overwrite_ each other rather than _merge_, it can be very difficult to get two incompatible addons to work together. For example, if you try to combine two addons that overwrite the creeper behavior (for example, one makes them very fast, and one makes them very large) the addon you have applied _second_ will overwrite the first.
This is mostly a problem with `player.json` (in either the RP or the BP), since this file is often used for gameplay purposes.
## Things that Cannot be Overwritten
Not everything can be overwritten, the following is a list of things that cannot be overwritten using any of the described methods:
- Vanilla items (Not all)
- Vanilla blocks
- Vanilla fogs (create a fog with another namespace and change it everywhere it is used)

161
docs/wiki/concepts/shaders.md Normal file
View File

@@ -0,0 +1,161 @@
---
title: Shaders
mentions:
- SirLich
- Dreamedc2015
- yanasakana
- MedicalJewel
- SIsilicon
---
:::warning
The shaders on this page are incompatible with [Render Dragon](https://help.minecraft.net/hc/en-us/articles/360052771272-About-the-1-16-200-Update-for-Windows-10-). That means that they will not work on Windows and Console devices past 1.16.200, nor other devices past 1.18.30!
:::
## Overview
Shaders are divided into 2 folders: `glsl` and `hlsl`. For shaders to work on every device,
you need to code shaders in both languages. For testing on Windows, `hlsl` is enough.
When rewriting shaders from one language to another, there are few things to change,
like HLSL `float3` is `vec3` in GLSL. Mapping between those languages can be found [here](https://anteru.net/blog/2016/mapping-between-HLSL-and-GLSL/)
## Materials
Vertex, fragments, and sometimes geometry shaders are combined with some options
as materials and are required for custom shaders. To create new material,
you need to create a file, which matches the name of the .material file in the vanilla resource pack.
For example: `materials/particles.material`. Materials support inheritance by adding parent
material after a colon. For example: `entity_alpha:entity_base`
### Common material definition fields
| **Field name** | **Description** | **Example value** | **Notes** |
| ---------------- | --------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vertexShader` | Path to the shader relative to hlsl/glsl folder | | For HLSL shader, `.hlsl` suffix is added. |
| `fragmentShader` | Path to the shader relative to hlsl/glsl folder | | For HLSL shader, `.hlsl` suffix is added. |
| `vertexFields` | An array of fields passed to vertex shader | | It's better to copy this field from vanilla material. |
| `variants` | An array of objects, which define variants of the material | | It's better to copy this field from vanilla material. |
| `+defines` | An array of `#define` directives to add to the shader source | | Useful for reusing shader, but changing some minor setting. |
| `+states` | An array of states to enable | `["Blending", "DisableAlphaWrite", "DisableDepthWrite"]` | For OpenGL implementation, this is equivalent to [glEnable](https://www.khronos.org/registry/OpenGL-Refpages/gl2.1/xhtml/glEnable.xml) call. |
| `-defines` | An array of `#defines` directives to remove from inherited `+defines` | | |
| `+samplerStates` | An array of objects, defining how texture at certain index is treated | `{ "samplerIndex": 0, "textureFilter": "Point" }` | `textureFilter` specifies how to sample the texture and `textureWrap` specifies the behavior, when accessing outside of the texture dimensions. |
| `msaaSupport` | Multisample anti-aliasing support | `Both` | |
| `blendSrc` | Specifies how the color source blending factors are computed | `One` | For OpenGL implementation, this is equivalent to [glBlendFunc](https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glBlendFunc.xhtml) call. |
| `blendDst` | Specifies how the color destination blending factors are computed | `One` | For OpenGL implementation, this is equivalent to [glBlendFunc](https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/glBlendFunc.xhtml) call. |
Example:
<CodeHeader></CodeHeader>
```json
{
"materials": {
"version": "1.0.0",
"particle_debug": {
"vertexShader": "shaders/particle_generic.vertex",
"fragmentShader": "shaders/particle_debug.fragment",
"vertexFields": [
{ "field": "Position" },
{ "field": "Color" },
{ "field": "UV0" }
],
"+samplerStates": [
{
"samplerIndex": 0,
"textureFilter": "Point"
}
],
"msaaSupport": "Both"
}
}
}
```
For all the details about material files and possible field values, check [material file JSON schema](https://github.com/stirante/bedrock-shader-schema/blob/master/materials.schema.json).
## Troubleshooting
### Shader doesn’t change
Every time there is a change in the shader, you need to restart Minecraft to recompile the shader completely.
### Compilation error
When there is a shader compilation error, a line number is usually specified where the error occurred. You need to check a few lines above the one set in error because Minecraft adds `#define` directives before compilation.
### Couldn’t find constant buffer named: $Globals
I couldn’t accurately find the actual cause of this error, but it seems to be somehow connected to global variables. Removing them (initializing them in the `main` function or changing them to `#define` directives) seems to fix the problem.
## Tips and tricks
### Passing variables to the shader
You can pass variables to the shader from a particle or an entity by changing entity color.
Input color is clamped to `<0.0, 1.0>`. To pass more significant values, you need to divide by max value (or at least some considerable number).
### Using time in shader
`TIME` variable is a number of seconds as `float` and is global for all shaders. For time-based on particle lifetime, you need to pass this:
<CodeHeader></CodeHeader>
```json
"minecraft:particle_appearance_tinting": {
"color": ["variable.particle_age/variable.particle_lifetime", 0, 0, 1]
}
```
Then in the shader, use `PSInput.color.r` as time, where `0.0` is particle birth and `1.0` is particle death.
### Camera direction towards the entity
For entity shaders, you can make the shader dependent on the camera direction towards the entity.
- Add to `PS_Input` in vertex and fragment shader new field
<CodeHeader></CodeHeader>
```
float3 viewDir: POSITION;
```
- After that, add to vertex shader this line
<CodeHeader></CodeHeader>
```
PSInput.viewDir = normalize((mul(WORLD, mul(BONES[VSInput.boneId], float4(VSInput.position, 1)))).xyz);
```
- In the fragment shader, use `PSInput.viewDir` to make changes depending on camera rotation
### Debugging values
The easiest way to debug a value is to turn it into color and render it like this.
<CodeHeader></CodeHeader>
```
PSOutput.color = float4(PSInput.uv, 0., 1.);
```
This should create a red-green gradient, showing that the values of `uv` are between `<0, 0>` and `<1, 1>`.
You can use the debug shader I wrote [based on this shader](http://mew.cx/drawtext/drawtext).
Right now, this shader will display values of the color passed to the shader. To display another value, change line 70 in hlsl shader to
<CodeHeader></CodeHeader>
```
int ascii = getFloatCharacter( cellIndex, <float4 vector here> );
```
GLSL version of debugging shader may crash Minecraft, use only for debugging.
[Download debug shader](http://files.stirante.com/debugShader.zip)
![](/assets/images/knowledge/shaders/debugShader.gif)

331
docs/wiki/concepts/sounds.md Normal file
View File

@@ -0,0 +1,331 @@
---
title: Sounds
tags:
- intermediate
mentions:
- SirLich
- solvedDev
- Joelant05
- aexer0e
- MedicalJewel105
- Justash01
- DasEtwas
- TheItsNameless
- ThomasOrs
---
In bedrock, we can add custom sounds without overwriting any vanilla sounds. This is done by adding files to the resource pack.
:::tip
The best way to learn about sounds is by downloading and playing around with the default resource pack.
:::
### Folder Structure
There are two main files that we edit when we want to add sounds. Note how `sound_definition` is nested inside `sounds`.
Sound files themselves are added inside of the `sounds` folder, and can be any of the following formats.
<FolderView :paths="[
'RP/sounds.json',
'RP/sounds/sound_definitions.json',
'RP/sounds/example.wav',
'RP/sounds/example.ogg',
'RP/sounds/example.fsb',
]"></FolderView>
## sound_definitions.json
`sound_definitions.json` is where we define new sound short-names. This should be thought of as typing a `short-name` or `id` to a physical sound path. Here is an example, `sound_definitions.json`, that adds a new trumpet sound called `example.toot`:
<CodeHeader>RP/sounds/sound_definitions.json</CodeHeader>
```json
{
"format_version": "1.14.0",
"sound_definitions": {
"example.toot": {
"category": "neutral",
"sounds": ["sounds/trumpet"]
}
}
}
```
Sounds added in this way can be triggered using `/playsound`. Please note that `playsound` does not auto-correct, so you will need to be careful in your typing.
:::warning
New files referenced by file path, such as sounds, DO need a complete client restart to load. This means that if sounds don't work, you should restart your entire MC client rather than just reloading the world.
:::
### /playsound volume notes
The game will clamp the sound volume to at most 1.0 before multiplying it with the sound definition's volume.
For `/playsound`, the maximum hearable range of a sound is given by `min(max_distance, max(volume * 16, 16))`.
If `"max_distance"`is not given in the sound's definition, it is equivalent to `playsound_volume * 16`.
Approximate sound attenuation by distance. The actual graph might not be linear.
![](/assets/images/concepts/sounds/sound_graph.png)
Shown above is the approximate sound attenuation factor by distance **for playing sounds with a volume parameter greater than or equal to 1**. Notice how the playsound `<volume>` limits the sound's audible range.
The axis `distance` is the distance of the sound listener (player) to the sound source. The corresponding `volume` axis' value is the factor for the playsound volume capped to 1, multiplied by the sound definition's volume to get the final volume of the sound you hear. As an expression this could be written as: `final_volume = min(playsound_volume, 1) * graph_volume * sound_definition_volume`.
**Note:** Attenuation by distance of the hearable sound's volume is not affected by the volume parameter given in the command.
For example, `mob.ghast.affectionate_scream` sets `"min_distance": 100.0`, but can only be heard from at most 16 blocks away when using `/playsound` with volume 1 to play it. Specifying a greater volume value increases the audible range. When using a large enough volume to hear the sound farther away, the sound will get quieter only after a distance of more than 100.0.
To make a sound which can be heard far away but also drops in volume continuously over distance, one can add e.g. `"volume": 0.01`and use large `<volume>` values in the playsound command. The high value for the `/playsound` volume will produce a large audible range (e.g. a volume of 4 is 64 blocks as calculated above), while the low volume will prevent the played sound from capping at 1.0 too soon.
### Top Level Keys
In the example above, I showed two `top-level` fields: `category` and `sounds`. Sounds will be discussed in further detail below, but the other `top-level` keys will be discussed here:
#### Categories
Categories are used internally by the engine to decide how each sound is played. We can utilize different channels to get other effects.
| Category | Note |
| -------- | ----------------------------------------------- |
| weather | |
| block | |
| bucket | |
| bottle | |
| ui | Sounds in this category will ignore range limit |
| player | |
| hostile | |
| music | |
| record | |
| neutral | |
#### min_distance
The distance from the sound source after which sound volume is attenuated. Default value: 0.0. It must be a float (eg. 1.0), or the property will be ignored.
#### max_distance
The distance from the sound source after which the sound volume is the quietest (if in range). It must be a float (eg. 1.0), or the property will be ignored.
### Sound definitions
In the example above, I showed `sounds` as simply a list with a single path. This is good for simple sounds but does not have much power. For starts, I can add multiple sounds to the list. These sounds will be randomized when played:
<CodeHeader>RP/sounds/sound_definitions.json</CodeHeader>
```json
{
"format_version": "1.14.0",
"sound_definitions": {
"example.toot": {
"category": "neutral",
"sounds": [
"sounds/trumpet",
"sounds/trumpet2",
"sounds/trumpet3"
]
}
}
}
```
Additionally, we can define each sound as an object instead of a string. This allows us finer control and unlocks some new settings. The string/object style can be mixed and matched.
#### name
The path to the file, such as: `"sounds/music/game/creative/creative1"`
#### stream
Limits the sound only to be played a limited number of instances at a time. Will cause the game to not load the entire sound data into memory while playing, but rather in smaller parts while playing, thus using less memory. Good for improving performance on sound heavy worlds.
#### volume
How loud the sound should play, from `0.0` to `1.0`. Sounds cannot be made more audible than initially encoded. Set to `1.0` by default.
Sounds in custom resource packs can have working values greater than 1.0.
#### load_on_low_memory
Forces the loading of the sound even when nearing low memory. "load_on_low_memory" is now deprecated as of 1.16.0
#### pitch
The pitch of the sound (how low/high it sounds). Should be a positive value. For example, `2.3` will let the sound play 2.3 times as quickly and thus at higher pitch. Set to `1.0` by default.
#### is3D
`true` makes the sound directional. Set to `true` for all sounds by default. Ignored for `music` and `ui` sounds. Only sounds with `false` will play stereo sound.
#### interruptible
Set to `true` by default.
### weight
If there is more than one sound in the list, the sound to be played is chosen randomly. `"weight"` (integer value like 5) will give the relative chance that this sound is chosen from the list. For example, if there are two sounds in the list, one with `"weight": 10` and the other with `"weight": 2`, the first will be played approximately 5 times more likely than the second (accurately: `10 / (10 + 2) = 83.3%` chance vs. `2 / (10 + 2) = 16.7%` chance) . Set to `1` by default.
### Example
Here is a more realistic example containing these options:
<CodeHeader>RP/sounds/sound_definitions.json#sound_definitions</CodeHeader>
```json
"block.beehive.drip": {
"category": "block",
"max_distance": 8,
"sounds": [
{
"name": "sounds/block/beehive/drip1",
"load_on_low_memory": true
},
"sounds/block/beehive/drip2",
"sounds/block/beehive/drip3",
"sounds/block/beehive/drip4"
]
}
```
## sounds.json
If we want our sounds to run automatically, we can add them into the `sounds.json` file. This will tie the sound definitions directly to game events and cause them to play without needing to trigger with `/playsound`.
Sounds can be added into various categories:
| Category | Note |
| ----------------------- | -------------------------------------------------------------------------------- |
| individual_event_sounds | Contains sounds like beacon activation, chest-close, or explode |
| block_sounds | Contains hit, step, and break sounds for blocks |
| entity_sounds | Contains death, ambient, hurt, etc. sounds for entities (Including custom ones!) |
| interactive_sounds | WIP |
### Adding Entity Sounds
I assume that sounds can be added in other categories, but I personally only have experience adding sounds into the `entities` category. Entity sounds are automatically played at various points in the entities life-cycle.
Common events:
| Events | Note |
| ---------- | -------------------------------------------------------- |
| ambient | Played randomly, such as grunts, clucks, or ghast noises |
| hurt | Played when damaged |
| death | Played when it dies |
| step | Played when the entity moves along the ground |
| fall.big | For hitting the ground from a high height |
| fall.small | For hitting the ground from a low height |
| splash | For splashing in the water |
| attack | For melee attacking |
| shoot | For shooting projectiles |
There are also many sound events, which _most likely_ trigger automatically, but which I don't have details for, such as:
| Unknown Categories |
| ------------------ |
| breathe |
| splash |
| swim |
| ambient.in.water |
| death.in.water |
| jump |
| eat |
| hurt.in.water |
| mad |
| stare |
| sniff |
| sleep |
| spit |
| warn |
| scream |
### Example
<CodeHeader>RP/sounds.json</CodeHeader>
```json
{
"entity_sounds": {
"entities": {
"wiki:elephant": {
"volume": 1,
"pitch": [0.9, 1.0],
"events": {
"step": {
"sound": "elephant.step",
"volume": 0.18,
"pitch": 1.1
},
"ambient": {
"sound": "elephant.trumpet",
"volume": 0.11,
"pitch": 0.9
}
}
}
}
}
}
```
## Adding sounds to Animations
Sounds played in animations function based off of `short-name` definitions in the RP entity file.
This example shows playing a wing-flap sound, synced with an animation.
<CodeHeader>RP/entities/dragon.json#minecraft:client_entity/description</CodeHeader>
```json
"sound_effects": {
"wing_flap": "wiki.dragon.wing_flap" //where wiki.dragon.roar is a sound defined in sound_definitions
}
```
<CodeHeader>RP/animations/dragon.json#animations/animation.dragon.flying</CodeHeader>
```json
"sound_effects": {
"3.16": {
"effect": "wing_flap"
}
}
```
## Adding sounds to Animation Controllers
You can play sounds within animation controllers in a similar way that animations can be.
This example shows playing an explosion sound, synced using an animation controller.
<CodeHeader>RP/entities/custom_tnt.json#minecraft:client_entity/description</CodeHeader>
```json
"sound_effects": {
"explosion": "wiki.custom_tnt.explosion" //where wiki.custom_tnt.explosion is a sound defined in sound_definitions just like animation sounds.
}
```
<CodeHeader>RP/animation_controllers/custom_tnt.animation_controllers.json#controller.animation.custom_tnt</CodeHeader>
```json
"states":{
"default":{
"transitions":[
{
"explode_state":"q.mark_variant == 1"
}
]
},
"explode_state":{
"sound_effects":[
{
"effect":"explosion"
}
],
"transitions":[
{
"default":"q.mark_variant == 0"
}
]
}
}
```

95
docs/wiki/concepts/subpacks.md Normal file
View File

@@ -0,0 +1,95 @@
---
title: Subpacks
mentions:
- SirLich
- solvedDev
- Joelant05
- ChilRx
- SmokeyStack
- MedicalJewel105
- TheItsNameless
---
## What are Subpacks?
Subpacks allow you to select between different addon 'configurations'.
They are intended for texture resolutions to load on different memory capacities, but can also be used to create file variations in behavior and resource packs. These variations can be selected by clicking the gear icon and adjusting the slider.
## How do Subpacks work?
Files placed in you subpack folder will override files placed in your main addon folder, if the subpack is selected. For example, if your addon contains both `RP/textures/entities/ghost.png` and `RP/subpacks/pack_1/textures/ghost.png`, the second image file will replace the first, if subpack `pack_1` is selected.
For more information about how files override each other, please see our page on [overriding vanilla assets](/concepts/overwriting-assets).
## Creating Subpacks
- To start adding a subpack you need to create a `subpacks` folder inside the root of your `BP`/`RP`.
- Then inside the `subpacks` folder add a folder for each subpack you want to have
e.g.
<FolderView :paths="[
'RP/subpacks/subpack_1',
'RP/subpacks/subpack_2'
]"></FolderView>
- Inside each of these folders you can add the content of each subpack.
This can be anything that normally goes in your behavior or resource pack.
e.g.
<FolderView :paths="[
'RP/subpacks/subpack_1/textures/blocks/dirt.png',
'RP/subpacks/subpack_1/textures/items/example_item.png',
'RP/subpacks/subpack_2/textures/blocks/dirt.png',
'RP/subpacks/subpack_2/textures/items/example_item.png'
]"></FolderView>
## Manifest Part
To register the subpacks in the manifest you need to add `subpacks` and this contains an array of subpacks.
Example:
<CodeHeader>RP/manifest.json</CodeHeader>
```json
{
"format_version": 2,
"header": {
"name": "Pack Name",
"description": "Pack Description",
"uuid": "2fc2dd6f-86cb-4370-af70-21490a1ae471",
"version": [1, 0, 0],
"min_engine_version": [1, 13, 0]
},
"modules": [
{
"type": "resources",
"uuid": "f6821b4a-1854-44fc-a8a4-0c2847ffda46",
"version": [1, 0, 0]
}
],
"subpacks": [
{
"folder_name": "subpack_1",
"name": "First Subpack",
"memory_tier": 0
},
{
"folder_name": "subpack_2",
"name": "Second Subpack",
"memory_tier": 1
}
]
}
```
- `name` - name that will show when selecting subpacks.
- `memory_tier`- amount of RAM that device must have to enable this subpack. 1 memory tier = 0.25 GB.
- `folder_name` - name of the folder to be used for this subpack, for example in the examples above this would be `subpack_1` or `subpack_2`.
## Known Things
If you add only one subpack, there will be 2 options at the subpacks selection section, however second resolution (no subpack actually) does **not** make content in the root folder override subpacks.

156
docs/wiki/concepts/text-and-translations.md Normal file
View File

@@ -0,0 +1,156 @@
---
title: Text and Localization
mentions:
- ThijsHankelMC
- SirLich
- aexer0e
- MedicalJewel105
- Luthorius
- Fabrimat
- TheDoctor15
- Hatchibombotar
- ChibiMango
- SmokeyStack
- Sprunkles
---
Minecraft is a game with fully localized text in languages all over the world. To achieve this, Minecraft employs a system where internal **translation keys** are assigned values on a per-language basis. Minecraft will generate translation keys for custom entities, items, and blocks, and it is up to us to assign them a localized name in our resource pack.
## Language Files
### File Location
Language files typically go within the resource pack in the "texts" folder as files with the `.lang` file extension. These files can be placed in the behavior pack, but the only translatable text it can change is the pack manifest's name and description.
<FolderView :paths="[
'RP/texts/en_US.lang',
'RP/texts/languages.json',
'RP/manifest.json'
]"
></FolderView>
Minecraft supports 29 languages currently, as described in [§ Vanilla Languages](/concepts/text-and-translations#vanilla-languages).
### Format
The format for a language file is rather straightforward. Translations are supplied as key-value pairs separated by an equals sign (`=`), the key being a translation key and the value being a string. Values cannot contain newline characters.
```toml
wiki.example_translation.line_1=The first line!
wiki.example_translation.line_2=Some more information following the first line.
```
Comments may be added with two pound signs (`##`), either as line comments or in-line comments. All text after the pound signs are a comment until the next line.
:::warning
Trailing spaces are not trimmed for in-line comments. If you want to indent a comment, use the Tab character.
:::
```toml
## Translator note: I thought this would be funny to put here.
item.flint_and_steel.name=Flint and Steve ##[sic]
```
A translation can contain substitutions in place of text. Substitutions can either be ordered (`%1`, `%2`, etc.) or not ordered (`%s`). Vanilla translations have their values filled in by the game, while players can manually set the substitutions' values with commands that use the raw JSON text format, like with [`/tellraw`](/commands/tellraw).
```toml
commands.op.success=Opped: %s
immersive_reader.book_page_header=Page %1 of %2
```
### Usage
Localization can be done just about anywhere text can be used, including (but not limited to):
- Pack name and description
- Entity, item, or block names
- Pages in a book
- Lines on a sign
- `/tellraw` and `/titleraw` commands
- Text in dialogue
Some text cannot be translated however, such as for an item renamed in an anvil.
## Localization
:::tip
It is good practice create a copy of your language file for each major language your pack supports. For example, to support full English one should create both an `en_US.lang` and an `en_GB.lang` file, to cover English in both the United States and Great Britain countries, respectively.
:::
When editing language files one must also add a `languages.json` file in the `texts` folder containing an array with each of the languages you plan to change. This lets Minecraft know that it should apply localization for these languages.
<CodeHeader>RP/texts/languages.json</CodeHeader>
```json
[
"en_US",
"en_GB",
"fr_FR"
]
```
### Custom Languages
With a global resource pack, custom languages may be introduced through the `languages.json` and `language_names.json` files. Once the pack is applied globally the language can be changed in the "Language" tab of the in-game settings.
For the following examples, lets assume that we have 2 fully functional language files, one named `xx_XX.lang`, and another named `yy_YY.lang`.
<CodeHeader>RP/texts/languages.json</CodeHeader>
```json
[
"xx_XX",
"yy_YY"
]
```
`language_names.json` is an array as well, but this time to define the names to display for the languages.
<CodeHeader>RP/texts/language_names.json</CodeHeader>
```json
[
[ "xx_XX", "New Language (Custom Language #1)" ],
[ "yy_YY", "Wiki-Speak (Custom Language #2)" ]
]
```
:::warning
Whenever using a custom language, make sure to unequip the language before you disable the Resource Pack which it is stored in, or else Minecraft will crash.
:::
### Vanilla Languages
The following is a table of the 29 languages Minecraft supports by default.
| File ID | Language | Country |
| ---------- | --------------------- | -------------- |
| id_ID | Indonesian | Indonesia |
| da_DK | Danish | Denmark |
| de_DE | German | Germany |
| en_GB | English | Great Britain |
| en_US | English | North America |
| es_ES | Spanish | Spain |
| es_MX | Mexican Spanish | Mexico |
| fr_CA | Canadian French | Canada |
| fr_FR | French | France |
| it_IT | Italian | Italy |
| hu_HU | Hungarian | Hungary |
| nl_NL | Dutch | Netherlands |
| nb_NO | Bokmål | Norway |
| pl_PL | Polish | Poland |
| pt_BR | Brazilian Portuguese | Brazil |
| pt_PT | Portuguese | Portugal |
| sk_SK | Slovak | Slovakia |
| fi_FI | Finnish | Finland |
| sv_SE | Swedish | Sweden |
| tr_TR | Turkish | Turkey |
| cs_CZ | Czech | Czech Republic |
| el_GR | Greek | Greece |
| bg_BG | Bulgarian | Bulgaria |
| ru_RU | Russian | Russia |
| uk_UA | Ukrainian | Ukraine |
| ja_JP | Japanese | Japan |
| zh_CN | Chinese (Simplified) | China |
| zh_TW | Chinese (Traditional) | Taiwan |
| ko_KR | Korean | Korea |

43
docs/wiki/concepts/textures-list.md Normal file
View File

@@ -0,0 +1,43 @@
---
title: textures_list.json
mentions:
- SirLich
- solvedDev
- Joelant05
- AFoxyToast
- TheItsNameless
---
## General Overview
The `textures_list` file is Minecraft's way of *caching* each texture so that it can retrieve it faster than looking through each image in your textures folder. This is especially important when you have an abundance of textures, where Minecraft could potentially mess up and swap textures or even not load them at all. Minecraft tends to throw a content log _warning_ if you don't have the textures listed in the file. You can ignore it if you have a small amount, but it is recommended that you list the textures anyway.
## What textures can be used in the file?
Any texture! Any textures can and _should_ be used in the textures_list.json file for best practice and performance.
## File Structure
The structure is simple. The file itself is in `RP/textures` and is named `textures_list.json`. The file includes the file path to every texture you want in the file:
<CodeHeader>RP/textures/textures_list.json</CodeHeader>
```json
[
"textures/blocks/foo",
"textures/blocks/bar",
"textures/items/foo",
"textures/items/bar",
"textures/models/foo",
"textures/models/bar",
"textures/entity/foo",
"textures/entity/bar"
]
```
## Automating
If you have a lot of textures, this could obviously be tedious to go and list all the texture paths. In this case you can start to use [Regolith](https://bedrock-oss.github.io/regolith/) with its wonderful filters.

70
docs/wiki/documentation/advanced-molang.md Normal file
View File

@@ -0,0 +1,70 @@
---
title: Advanced Molang
toc_max_level: 2
mentions:
- Ciosciaa
- TheItsNameless
---
## Values
- All expressions in Molang return a value for the sake of checks against equality. Most expressions return `0`. Notably, assignments return the value assigned and loops return the resolved value of the looping statements, if one would exist.
- All values in Molang are effectively single-precision floats.
- `this` is used to refer to the field's current value as it accumulated during evaluation. It is only observed to be usable in animations, but it may be usable elsewhere. As an example, if the accumulated transformations on the `x` `scale` of a bone would yield `62`, a final animation with a `x` `scale` of `-this` would resolve to `-62`, unsetting the prior transformations. This is used in vanilla animations in a number of places. Outside of animation contexts, `this` appears to always resolve to `0`.
### Booleans
- Booleans are usable in Molang. `true` resolves to `1`, and `false` resolves to `0`.
### Numbers
- You can use leading `0`s in front of numbers, for example, to line them up better in your code.
- Numbers can use exponential notation, such as `2.5e2`, which would be equal to 250. `e` can be suffixed with `+` or `-` to direct the power.
- Numbers may be suffixed with a single `f`, often used to denote a floating point value. This can be found across vanilla code, but it is not believed to have any functionality.
### Strings
- Strings use `\` (`\\` in escaped JSON) as some sort of escape or perhaps something else. It is unknown what functionality this has. It is known that the subsequent 2 characters are handed off to their own sub-parser, which does not exit correctly on a closing `'`; this means the Molang string `"v.type = '\\x';"` is invalid. `'`, which is normally disallowed on its own as it would represent the end of the string, is allowed in the 2 characters following a `\`.
- String values are (mostly) incremental as they are represented against floats. It is possible to compare 2 individual character strings using equality or comparison operators or even to effectively "adjust" the contents of a single-character string. Multi-character behavior of such is unknown.
## Operators
The complete precedence list, from first to last evaluated:
1. `()` and `[]`
2. `->`
3. `!` and `-` (unary negation)
4. `*` and `/`
5. `+` and `-` (binary subtraction)
6. `<`, `<=`, `>`, and `>=`
7. `==` and `!=`
8. `&&`
9. `||`
10. `?` and `? :`
11. `??`
12. `=`
13. `return`
- Operators are considered from left to right for all operators except the conditionals.
- Multiple `->` cannot be used in the same statement.
- Logical operators short-circuit.
## Statements
- Assignments return the value assigned. You can therefore chain assignments if you need separate variables to work with from a single value, such as with `v.iterator_x = (v.iterator_z = math.random_integer(16, 32));`.
- The last statement inside a brace scope does not need to end with a `;`.
- Brace scopes can be used anywhere an expression can be used. `v.spawn_point ?? {v.target = false;};`, for example, would set `v.target` to `false` if `v.spawn_point` were not defined.
## Collections
- Entity iterables (such as the result of `q.get_nearby_entities`) are their own "type". They are not compatible with subscripts.
- Arrays, likewise, are not compatible with entity iterable operations, such as `q.count`.
- The result of array subscripts cannot directly be an argument to `+`, `-`, `*`, or `/` but may still be used directly as function parameters (even math functions) or with other operators.
## Evaluation
- `initialize` and `pre_animation` are lazily concatenated. Molang strings in these arrays must be syntactically valid independently, but the basic concatenation of all independent strings must also be a valid Molang input.
## Limits
- Molang showed no reasonable limits to any language functionality, aside from numeric size. Loop counts, string lengths, Molang input length, collection size, etc., were observed to hold in very unreasonable situations.

180
docs/wiki/documentation/creative-categories.md Normal file
View File

@@ -0,0 +1,180 @@
---
title: Menu Categories
mentions:
- Warhead51707
- yanasakana
- SirLich
- SmokeyStack
- MedicalJewel105
- Chikorita-Lover
- MiemieMethod
- retr0cube
- TheItsNameless
- QuazChick
---
Menu categories determine where items and blocks appear inside of the creative inventory and recipe book.
- A `category` can be defined to place the item under a tab (such as construction). Click [here](#list-of-categories) for a list of valid categories.
- A `group` specifies which expandable group the item is placed into. If you use a custom value, a new expandable group won't be created, however items with the group will be placed next to each other in the creative inventory. Click [here](#list-of-groups) for a list of expandable groups.
- You can also set `is_hidden_in_commands` to true to remove this block/item from commands, such as `/give` and `/setblock`.
If `menu_category` is omitted, the item will only be accessible through commands and won't appear in the creative inventory or recipe book.
**NOTE:** The menu category of custom spawn eggs cannot be modified. You must instead create a custom item with the `minecraft:entity_placer` component.
<CodeHeader></CodeHeader>
```json
"menu_category": {
"category": "construction", // Tab the item is placed under
"group": "itemGroup.name.door", // Optional - Group the item is placed into
"is_hidden_in_commands": false // Optional - default is false (item is usable in commands)
}
```
:::danger HIDDEN ITEMS INACCESSIBLE IN COMMANDS ([MCPE-177866](https://bugs.mojang.com/browse/MCPE-177866))
Currently, setting the category to "none" in a custom item (not block) prevents the item from being used in commands, overriding the "is_hidden_in_commands" option. This issue doesn't affect blocks.
:::
## Block Example
<CodeHeader>BP/blocks/balsa_wood.json</CodeHeader>
```json
{
"format_version": "1.20.50",
"minecraft:block": {
"description": {
"identifier": "wiki:balsa_wood",
"menu_category": {
"category": "nature",
"group": "itemGroup.name.wood" // Placed into an expandable group
}
}
}
}
```
## Item Example
<CodeHeader>BP/items/dagger.json</CodeHeader>
```json
{
"format_version": "1.20.50",
"minecraft:item": {
"description": {
"identifier": "wiki:dagger",
"menu_category": {
"category": "equipment",
"is_hidden_in_commands": true // Item cannot be used in commands
}
}
}
}
```
## List of Categories
_For use with `menu_category` parameter, `category`._
| Category | Description |
| ------------ | -------------------------------------------------------- |
| construction | Added to the "Contruction" tab. |
| equipment | Added to the "Equipment" tab. |
| items | Added to the "Items" tab. |
| nature | Added to the "Nature" tab. |
| none | Not added to a tab and only accessible through commands. |
## List of Groups
_For use with the `menu_category` parameter, `group`._
<!-- page_dumper_start -->
| Creative Categories: |
| --------------------------------- |
| itemGroup.name.anvil |
| itemGroup.name.arrow |
| itemGroup.name.axe |
| itemGroup.name.banner |
| itemGroup.name.banner_pattern |
| itemGroup.name.bed |
| itemGroup.name.boat |
| itemGroup.name.boots |
| itemGroup.name.buttons |
| itemGroup.name.candles |
| itemGroup.name.chalkboard |
| itemGroup.name.chest |
| itemGroup.name.chestboat |
| itemGroup.name.chestplate |
| itemGroup.name.concrete |
| itemGroup.name.concretePowder |
| itemGroup.name.cookedFood |
| itemGroup.name.copper |
| itemGroup.name.coral |
| itemGroup.name.coral_decorations |
| itemGroup.name.crop |
| itemGroup.name.door |
| itemGroup.name.dye |
| itemGroup.name.enchantedBook |
| itemGroup.name.fence |
| itemGroup.name.fenceGate |
| itemGroup.name.firework |
| itemGroup.name.fireworkStars |
| itemGroup.name.flower |
| itemGroup.name.glass |
| itemGroup.name.glassPane |
| itemGroup.name.glazedTerracotta |
| itemGroup.name.goatHorn |
| itemGroup.name.grass |
| itemGroup.name.hanging_sign |
| itemGroup.name.helmet |
| itemGroup.name.hoe |
| itemGroup.name.horseArmor |
| itemGroup.name.leaves |
| itemGroup.name.leggings |
| itemGroup.name.lingeringPotion |
| itemGroup.name.log |
| itemGroup.name.minecart |
| itemGroup.name.miscFood |
| itemGroup.name.mobEgg |
| itemGroup.name.monsterStoneEgg |
| itemGroup.name.mushroom |
| itemGroup.name.netherWartBlock |
| itemGroup.name.ore |
| itemGroup.name.permission |
| itemGroup.name.pickaxe |
| itemGroup.name.planks |
| itemGroup.name.potion |
| itemGroup.name.potterySherds |
| itemGroup.name.pressurePlate |
| itemGroup.name.rail |
| itemGroup.name.rawFood |
| itemGroup.name.record |
| itemGroup.name.sandstone |
| itemGroup.name.sapling |
| itemGroup.name.sculk |
| itemGroup.name.seed |
| itemGroup.name.shovel |
| itemGroup.name.shulkerBox |
| itemGroup.name.sign |
| itemGroup.name.skull |
| itemGroup.name.slab |
| itemGroup.name.smithing_templates |
| itemGroup.name.splashPotion |
| itemGroup.name.stainedClay |
| itemGroup.name.stairs |
| itemGroup.name.stone |
| itemGroup.name.stoneBrick |
| itemGroup.name.sword |
| itemGroup.name.trapdoor |
| itemGroup.name.walls |
| itemGroup.name.wood |
| itemGroup.name.wool |
| itemGroup.name.woolCarpet |
*Last updated for 1.20.10*
<!-- page_dumper_end -->

106
docs/wiki/documentation/file-types.md Normal file
View File

@@ -0,0 +1,106 @@
---
title: File Types
max_toc_level : 3
mentions:
- Ciosciaa
- SirLich
---
A number of file types exist for *Minecraft*, all for importing content. All *Minecraft* files are ZIP archives renamed to use a `mc…` extension. These archives can currently be divided into three sets:
- **Levels (`mcworld` and `mcproject`)**: level data and associated resources for worlds and projects
- **Assets (`mcpack` and `mctemplate`)**: cosmetics or supporting assets for worlds
- **Composites (`mcaddon` and `mceditoraddon)`**: used to import up to one world or project and any number of asset types
All file types for Minecraft can be opened as any file, launching Minecraft and importing the content. When packages are imported, they are automatically unpacked into their constituent files and directories. If it was not already open, most file types will launch Minecraft in normal mode; `mcproject` and `mceditoraddon` will instead launch Minecraft into Editor mode.
# Levels
Levels represent save data and resources for regular worlds and Editor projects. All levels, regardless of mode, are imported to `minecraftWorlds` in the `com.mojang` directory.
Importing an exact duplicate of an existing saved level will create a duplicate saved level. Composite archives will only import one level if multiple are included, including across nested composite archives.
## Worlds
`mcworld`
Archive encapsulating an individual world
World archives can be created a few different ways:
- Zipping the *contents* of a world directory and renaming the extension from `zip` to `mcworld`
- Using the "Export World" button on the Game settings screen for a world
- In Editor mode, exporting the world from the File → Export as → Playable world menu option. The world will be saved to the `projectbackups` directory in the `com.mojang` folder.
- In Editor mode, running the `/project export world` command. The world will be saved to the `projectbackups` directory in the `com.mojang` folder.
Importing a world package while *Minecraft* is launched in Editor mode will import the world as a project. The imported world will then be inaccessible outside Editor mode and will need to be re-exported as a world for playing. Editor extension packs bundled in a world archive will be retained on import outside Editor mode.
## Projects
`mcproject`
Archive encapsulating an individual Editor project
Project archives can be created two different ways:
- Zipping the *contents* of a project directory and renaming the extension from `zip` to `mcproject`.
- Using the "Export Project" button on the Game settings screen for a world
- In Editor mode, running the `/project export project` command. The world will be saved to the `projectbackups` directory in the `com.mojang` folder.
If *Minecraft* is not open, launching a `mcproject` file will open Editor mode. Importing a `mcproject` will fail if *Minecraft* is open but not in Editor mode.
# Assets
Asset archives represent a singular instance of a number of non-level contents:
- Behavior packs
- Resource packs
- Skin packs
- World templates
All asset archives include a manifest describing their contents. An asset archive will fail to import if its manifest UUID and version exactly matches an existing asset archive of the same type. Note that behavior and resource packs share the same UUID/version space. Behavior and resource packs self-contained within a world, project, or template will not count as duplicates for the sake of importing.
Both asset extensions, `mcpack` and `mctemplate`, appear to functionally behave the same. It's best practice to use `mcpack` for behavior, resource, and skin packs and `mctemplate` for world templates to make it more clear what's being installed. Any number of asset archives may be included in a composite archive.
## Packs
`mcpack`
Package representing an individual behavior pack, resource pack, skin pack, or world template. It's recommended only to use `mctemplate` for behavior packs, resource packs, or skin packs.
Packs are only created manually, by zipping the contents of a behavior pack, resource pack, or skin pack directory and renaming the extension from `zip` to `mcpack`. Behavior and resource packs are installed globally and do not conflict with matching behavior or resource packs installed in worlds, projects, or templates.
### Behavior Packs
Behavior packs are attached to servers to change or extend gameplay. Behavior packs are installed to the `behavior_packs` directory in the `com.mojang` folder.
Development behavior packs must be placed in the `development_behavior_packs` directory under `com.mojang` manually.
### Resource Packs
Resource packs are attached to clients to affect sounds, visuals, etc. Resource packs are installed to the `resource_packs` directory in the `com.mojang` folder.
Development resource packs must be placed in the `development_resource_packs` directory under `com.mojang` manually.
### Skin Packs
Skin packs are client-only packs for custom skins. Skin packs are installed to the `skin_packs` directory in the `com.mojang` folder.
Development skin packs must be placed in the `development_skin_packs` directory under `com.mojang` manually, but this feature appears non-functional.
## World Templates
`mctemplate`
Package representing an individual behavior pack, resource pack, skin pack, or world template. It's recommended only to use `mctemplate` for world templates.
World templates are installed to the `world_templates` directory under `com.mojang`. World templates can be constructed in a few different ways:
- Zipping the *contents* of a world directory, adding a world template manifest, and renaming the extension from `zip` to `mctemplate`
- In Editor mode, using the "Export Template" button on the Game settings screen for a world
- In Editor mode, running the `/project export template` command. The world will be saved to the `projectbackups` directory in the `com.mojang` folder.
# Composites
Composite archives are used to import up to *one* level archive and any number or combination of asset archives in a single import action. In general, contents to a composite must be packaged. Directories can also be given *on the top level* of a composite archive for importing asset types (behavior packs, resource packs, skin packs, and world templates) without needing to pre-package them. Nested sub-directories for organization may not be used.
Composite contents are treated as usual. For example, importing a `mcaddon` contianing a `mcworld` while in Editor mode will import the world as a project.
Composite archives may also contain any number or nesting of other composite archives, even across *Minecraft* modes. Nested composite archives cannot be used to get around the singular world import restriction.
Composites can only be constructed manually by zipping archives and asset types.
## Add-Ons
`mcaddon`
Generic composite content archive
Importing a `mcaddon` package while *Minecraft* is launched in Editor mode will import any contained world as a project. The imported world will then be inaccessible outside Editor mode and will need to be re-exported as a world for playing. Asset types are imported as usual.
## Editor Add-Ons
`mceditoraddon`
Composite content archive for Editor mode
If *Minecraft* is not open, launching a `mcproject` file will open Editor mode. Importing a `mcproject` will fail if *Minecraft* is open but not in Editor mode.

163
docs/wiki/documentation/fog-ids.md Normal file
View File

@@ -0,0 +1,163 @@
---
title: Fog IDs
mentions:
- SirLich
- MedicalJewel105
- TheItsNameless
---
## By Element X
| ID | Note |
| ---------------------------------------------- | -------------------------------------------------------------------------------- |
| minecraft:fog_bamboo_jungle | Fog used in the bamboo jungle. |
| minecraft:fog_bamboo_jungle_hills | Fog used in the bamboo jungle hills. |
| minecraft:fog_basalt_deltas | Fog used in the basalt deltas. Adds a gray-red tint to the edge of the sky |
| minecraft:fog_beach | Fog used in the beach biome. |
| minecraft:fog_birch_forest | Fog used in the birch forest |
| minecraft:fog_birch_forest_hills | Fog used in the birch forest hills biome. |
| minecraft:fog_cold_beach | Fog used in the cold beach biome. |
| minecraft:fog_cold_ocean | Fog used in the cold ocean biome. |
| minecraft:fog_cold_taiga | Fog used in the cold taiga biome. |
| minecraft:fog_cold_taiga_hills | Fog used in the cold taiga hills biome. |
| minecraft:fog_cold_taiga_mutated | Fog used in the mutated cold taiga biome. |
| minecraft:fog_crimson_forest | Fog used in the crimson forest biome. Adds a red tint to the edge of the sky |
| minecraft:fog_deep_cold_ocean | Fog used in the deep cold ocean biome. |
| minecraft:fog_deep_frozen_ocean | Fog used in the deep frozen ocean biome. |
| minecraft:fog_deep_lukewarm_ocean | Fog used in the deep lukewarm ocean biome. |
| minecraft:fog_deep_ocean | Fog used in the deep ocean biome. |
| minecraft:fog_deep_warm_ocean | Fog used in the deep warm ocean biome. |
| minecraft:fog_default | Default fog used in the game. |
| minecraft:fog_desert | Fog used in the desert biome. |
| minecraft:fog_desert_hills | Fog used in the desert hills biome. |
| minecraft:fog_extreme_hills | Fog used in the extreme hills biome. |
| minecraft:fog_extreme_hills_edge | Fog used in the extreme hills edge biome. |
| minecraft:fog_extreme_hills_mutated | Fog used in the mutated extreme hills biome. |
| minecraft:fog_extreme_hills_plus_trees | Fog used in the extreme hills with trees biome. |
| minecraft:fog_extreme_hills_plus_trees_mutated | Fog used in the mutated extreme hills with trees biome. |
| minecraft:fog_flower_forest | Fog used in the flower forest biome. |
| minecraft:fog_forest | Fog used in the forest biome. |
| minecraft:fog_forest_hills | Fog used in the forest hills biome. |
| minecraft:fog_frozen_ocean | Fog used in the frozen ocean biome. |
| minecraft:fog_frozen_river | Fog used in the frozen river biome. |
| minecraft:fog_hell | Fog used in the nether wastes biome. Adds a red tint to the edge of the sky |
| minecraft:fog_ice_mountains | Fog used in the ice mountains biome. |
| minecraft:fog_ice_plains | Fog used in the ice plains biome. |
| minecraft:fog_ice_plains_spikes | Fog used in the ice spikes biome. |
| minecraft:fog_jungle | Fog used in the jungle biome. |
| minecraft:fog_jungle_edge | Fog used in the jungle edge biome. |
| minecraft:fog_jungle_hills | Fog used in the jungle hills biome. |
| minecraft:fog_jungle_mutated | Fog used in the mutated jungle biome. |
| minecraft:fog_lukewarm_ocean | Fog used in the lukewarm ocean biome. |
| minecraft:fog_mega_spruce_taiga | Fog used in the mega spruce taiga biome. |
| minecraft:fog_mega_spruce_taiga_mutated | Fog used in the mega spruce mutated taiga biome. |
| minecraft:fog_mega_taiga | Fog used in the mega taiga biome. |
| minecraft:fog_mega_taiga_hills | Fog used in the mega taiga hills biome. |
| minecraft:fog_mega_taiga_mutated | Fog used in the mega mutated taiga biome. |
| minecraft:fog_mesa | Fog used in the mesa biome. |
| minecraft:fog_mesa_bryce | Fog used in the mesa bryce biome. |
| minecraft:fog_mesa_mutated | Fog used in the mutated mesa biome. |
| minecraft:fog_mesa_plateau | Fog used in the mesa plateau biome. |
| minecraft:fog_mesa_plateau_stone | Fog used in the stone mesa plateau biome. |
| minecraft:fog_mushroom_island | Fog used in the mushroom island biome. |
| minecraft:fog_mushroom_island_shore | Fog used in the mushroom island shore biome. |
| minecraft:fog_ocean | Fog used in the ocean biome. |
| minecraft:fog_plains | Fog used in the plains biome. |
| minecraft:fog_river | Fog used in the river biome. |
| minecraft:fog_roofed_forest | Fog used in the roofed forest biome. |
| minecraft:fog_savanna | Fog used in the savanna biome. |
| minecraft:fog_savanna_mutated | Fog used in the mutated savanna biome. |
| minecraft:fog_savanna_plateau | Fog used in the savanna plateau biome. |
| minecraft:fog_soulsand_valley | Fog used in the soulsand valley biome. Adds a dark green tint to the sky |
| minecraft:fog_stone_beach | Fog used in the stone beach biome. |
| minecraft:fog_sunflower_plains | Fog used in the sunflower plains biome. |
| minecraft:fog_swampland | Fog used in the swamp biome. |
| minecraft:fog_swampland_mutated | Fog used in the mutated swamp biome. |
| minecraft:fog_taiga | Fog used in the taiga biome. |
| minecraft:fog_taiga_hills | Fog used in the taiga hills biome. |
| minecraft:fog_taiga_mutated | Fog used in the mutated taiga hills biome. |
| minecraft:fog_the_end | Fog used in the end biome. Adds a black tint to the edge of the sky |
| minecraft:fog_warm_ocean | Fog used in the warm ocean biome. |
| minecraft:fog_warped_forest | Fog used in the warped forest biome. Adds a dark red tint to the edge of the sky |
[Original Credit](https://www.youtube.com/watch?time_continue=52&v=SA79ulIgypg&feature=emb_logo)
## Auto-generated
<!-- page_dumper_start -->
| ID | Biome used in |
| ---------------------------------------------- | -------------------------------- |
| minecraft:fog_bamboo_jungle | bamboo_jungle |
| minecraft:fog_bamboo_jungle_hills | bamboo_jungle_hills |
| minecraft:fog_basalt_deltas | basalt_deltas |
| minecraft:fog_beach | beach |
| minecraft:fog_birch_forest | birch_forest |
| minecraft:fog_birch_forest_hills | birch_forest_hills |
| minecraft:fog_cherry_grove | cherry_grove |
| minecraft:fog_cold_beach | cold_beach |
| minecraft:fog_cold_ocean | cold_ocean |
| minecraft:fog_cold_taiga | cold_taiga |
| minecraft:fog_cold_taiga_hills | cold_taiga_hills |
| minecraft:fog_cold_taiga_mutated | cold_taiga_mutated |
| minecraft:fog_crimson_forest | crimson_forest |
| minecraft:fog_deep_cold_ocean | deep_cold_ocean |
| minecraft:fog_deep_frozen_ocean | deep_frozen_ocean |
| minecraft:fog_deep_lukewarm_ocean | deep_lukewarm_ocean |
| minecraft:fog_deep_ocean | deep_ocean |
| minecraft:fog_deep_warm_ocean | deep_warm_ocean |
| minecraft:fog_default | default |
| minecraft:fog_desert | desert |
| minecraft:fog_desert_hills | desert_hills |
| minecraft:fog_extreme_hills | extreme_hills |
| minecraft:fog_extreme_hills_edge | extreme_hills_edge |
| minecraft:fog_extreme_hills_mutated | extreme_hills_mutated |
| minecraft:fog_extreme_hills_plus_trees | extreme_hills_plus_trees |
| minecraft:fog_extreme_hills_plus_trees_mutated | extreme_hills_plus_trees_mutated |
| minecraft:fog_flower_forest | flower_forest |
| minecraft:fog_forest | forest |
| minecraft:fog_forest_hills | forest_hills |
| minecraft:fog_frozen_ocean | frozen_ocean |
| minecraft:fog_frozen_river | frozen_river |
| minecraft:fog_hell | hell |
| minecraft:fog_ice_mountains | ice_mountains |
| minecraft:fog_ice_plains | ice_plains |
| minecraft:fog_ice_plains_spikes | ice_plains_spikes |
| minecraft:fog_jungle | jungle |
| minecraft:fog_jungle_edge | jungle_edge |
| minecraft:fog_jungle_hills | jungle_hills |
| minecraft:fog_jungle_mutated | jungle_mutated |
| minecraft:fog_lukewarm_ocean | lukewarm_ocean |
| minecraft:fog_mangrove_swamp | mangrove_swamp |
| minecraft:fog_mega_spruce_taiga | mega_spruce_taiga |
| minecraft:fog_mega_spruce_taiga_mutated | mega_spruce_taiga_mutated |
| minecraft:fog_mega_taiga | mega_taiga |
| minecraft:fog_mega_taiga_hills | mega_taiga_hills |
| minecraft:fog_mega_taiga_mutated | mega_taiga_mutated |
| minecraft:fog_mesa | mesa |
| minecraft:fog_mesa_bryce | mesa_bryce |
| minecraft:fog_mesa_mutated | mesa_mutated |
| minecraft:fog_mesa_plateau | mesa_plateau |
| minecraft:fog_mesa_plateau_stone | mesa_plateau_stone |
| minecraft:fog_mushroom_island | mushroom_island |
| minecraft:fog_mushroom_island_shore | mushroom_island_shore |
| minecraft:fog_ocean | ocean |
| minecraft:fog_plains | plains |
| minecraft:fog_river | river |
| minecraft:fog_roofed_forest | roofed_forest |
| minecraft:fog_savanna | savanna |
| minecraft:fog_savanna_mutated | savanna_mutated |
| minecraft:fog_savanna_plateau | savanna_plateau |
| minecraft:fog_soulsand_valley | soulsand_valley |
| minecraft:fog_stone_beach | stone_beach |
| minecraft:fog_sunflower_plains | sunflower_plains |
| minecraft:fog_swampland | swampland |
| minecraft:fog_swampland_mutated | swampland_mutated |
| minecraft:fog_taiga | taiga |
| minecraft:fog_taiga_hills | taiga_hills |
| minecraft:fog_taiga_mutated | taiga_mutated |
| minecraft:fog_the_end | the_end |
| minecraft:fog_warm_ocean | warm_ocean |
| minecraft:fog_warped_forest | warped_forest |
*Last updated for 1.20.10*
<!-- page_dumper_end -->

3
docs/wiki/documentation/index.md Normal file
View File

@@ -0,0 +1,3 @@
---
title: Documentation
---

618
docs/wiki/documentation/material-config-description.md Normal file
View File

@@ -0,0 +1,618 @@
---
title: Material Configuration Description
tags:
- expert
mentions:
- MedicalJewel105
- SmokeyStack
---
:::warning
Materials are not for the faint of heart. Be prepared for potential crashes, content log errors, and long loading times.
:::
## Foreword
This article is translated from https://mc.163.com/dev/mcmanual/mc-dev/mcguide/ - It is provided by Netease, the developers of china edition. The article will introduce the structure and configuration of the material file in detail.
## Material files
We will explain the material files of native Microsoft. First of all, the files under the directory are basically files with the suffix ".material". In addition, there are three important json files, namely common. json, fancy.json, sad.json.
Let's take a look at sad.json and fancy.json first. They are used to control the image quality performance. Each of them defines a list of material files. fancy.json usually defines several more material files than sad.json and may Some additional macros have been added to some material files, and the shader can do special processing by judging these macros:
<CodeHeader>sad.json</CodeHeader>
```json
[
{"path":"materials/sad.material"},
{"path":"materials/entity.material"},
{"path":"materials/terrain.material"},
{"path":"materials/portal.material"},
{"path":"materials/barrier.material"},
{"path":"materials/wireframe.material"}
]
```
<CodeHeader>fancy.json</CodeHeader>
```json
[
{"path":"materials/fancy.material", "+defines":["FANCY"]},
{"path":"materials/entity.material", "+defines":["FANCY"]},
{"path":"materials/terrain.material", "+defines":["FANCY"]},
{"path":"materials/hologram.material"},
{"path":"materials/portal.material", "+defines":["FANCY"]},
{"path":"materials/barrier.material"},
{"path":"materials/wireframe.material"}
]
```
It can be seen that fancy.json defines more fancy.material and hologram.material material files than sad.json, and also defines FANCY macros for multiple material files. The switch of in-game settings/video/exquisite texture is to control the switch between sad and fancy. When the fancy texture switch is turned on, the material file in fancy.json will take effect, and when it is turned off, the material file in sad.json will take effect.
In order to achieve better performance, the material files in fancy.json usually have more complex operations, while the materials in sad.json usually sacrifice a little rendering performance in exchange for better performance. If developers need to write more complex shaders, it is recommended to write a low-cost version at the same time, and then define them in fancy and sad respectively. Let the player control whether to turn on the corresponding effect through the exquisite texture option in the game.
<CodeHeader>common.json</CodeHeader>
```json
[
{"path":"materials/particles.material"},
{"path":"materials/shadows.material"},
{"path":"materials/sky.material"},
{"path":"materials/ui.material"},
{"path":"materials/ui3D.material"},
{"path":"materials/portal.material"},
{"path":"materials/barrier.material"},
{"path":"materials/wireframe.material"}
]
```
Compared with sad and fancy, they can be switched between each other. The material files defined in common.json will be loaded after entering the game. Material files are not loaded except those declared in common.json, sad.json, fancy.json.
## Material syntax
We use one of the material files entity.material to explain, open the file, we can see that the file starts with materials, and then defines the version number version as 1.0.0, these are fixed formats, which identify the parsing of this material file way, we can temporarily ignore it and not modify it.
You can see that the definition of each field in the material is in the form of a key-value pair, for example:
```json
[
"vertexShader": "shaders/entity.vertex",
]
```
The left side of the colon represents the key as vertexShader, and the right side represents the value shaders/entity.vertex;
There are also definitions in list form:
```json
[
"vertexFields": [
{ "field": "Position" },
{ "field": "Normal" },
{ "field": "UV0" }
],
]
```
The declaration with the symbol [ ] is a list, and then inside is the json definition of each child element.
## Overview of all property fields of the material
### Render state
#### `states`
Configure the rendering environment, which can have the following values:
- `EnableAlphaToCoverage`：An order-independent rendering method for translucent objects. This switch is only useful in environments that support MSAA. When enabled, the edges of objects will be more accurately softened and transitioned according to the transparency. It can also be used for some complex scenes with a large number of meshes overlapping.
- `Wireframe`： Draw wireframe mode
- `Blending`: Enables color blending mode, often used to render translucent objects. After declaring this, it is usually necessary to declare the blending factor blendSrc, blendDst
- `DisableColorWrite`： Do not write color values to the color buffer, none of the RGBA channels are written
- `DisableAlphaWrite`： Do not write transparency alpha values to the color buffer, allow RGB values to be written
- `DisableRGBWrite`： Do not write transparency RGB values to the color buffer, allow writing alpha values
- `DisableDepthTest`： Turn off depth testing
- `DisableDepthWrite`： Turn off depth writing
- `DisableCulling`: Render front and back simultaneously
- `InvertCulling`：Use front cropping. The default is back cropping. After declaring this, the back side is rendered and the front side is cropped.
- `StencilWrite`: Enable stencil mask writing
- `EnableStencilTest`： Enable stencil mask testing
### Shader path
#### `vertexShader`
The path to the vertex shader, usually shaders/XXX.vertex.
#### `vrGeometryShader` or `geometryShader`
The path of the geometry shader, usually shaders/XXX.geometry, is not used on the mobile side, and does not need to be modified.
#### `fragmentShader`
The path to the fragment shader, usually shaders/XXX.fragment.
### Shader macro definition
#### `defines`
Define macros for the shaders used. For code reuse, we use the same shader for many different materials. At this time, if you want to execute different logic somewhere in the shader according to the current material, you can judge it through the macro declared by the material defines. We can use the material entity_for_skeleton as an illustration. Here we can see that three macros USE_SKINNING, USE_OVERLAY, and NETEASE_SKINNING are defined.
```json
"entity_for_skeleton": {
"vertexShader": "shaders/entity.vertex",
"vrGeometryShader": "shaders/entity.geometry",
"fragmentShader": "shaders/entity.fragment",
"+defines": [ "USE_SKINNING", "USE_OVERLAY", "NETEASE_SKINNING" ],
"vertexFields": [
{ "field": "Position" },
{ "field": "Normal" },
{ "field": "BoneId0" },
{ "field": "UV0" }
],
"msaaSupport": "Both",
"+samplerStates": [
{
"samplerIndex": 0,
"textureFilter": "Point"
}
]
}
```
Looking at the vertex shader entity.vertex, there will be #ifdef, #else, #endif to judge the macro and execute different logic branches. These judgment statements of the macro are processed at compile time, unlike the if in the traditional shader. Else, the logic branch processed at compile time will not be generated in actual operation, and the performance will not be degraded due to the branch. In addition, it can be seen below that macros can also make multi-layer judgments. First, judge the NETEASE_SKINNING macro, and then judge the LARGE_VERTEX_SHADER_UNIFORMS macro in the internal execution logic:
```glsl
#ifdef NETEASE_SKINNING
MAT4 boneMat = transpose(mat3x4ToMat4(BONES_70[int(BONEID_0)]));
entitySpacePosition = boneMat * POSITION;
entitySpaceNormal = boneMat * NORMAL;
#else
#if defined(LARGE_VERTEX_SHADER_UNIFORMS)
entitySpacePosition = BONES[int(BONEID_0)] * POSITION;
entitySpaceNormal = BONES[int(BONEID_0)] * NORMAL;
#else
entitySpacePosition = BONE * POSITION;
entitySpaceNormal = BONE * NORMAL;
#endif
#endif
```
### Runtime state
#### Depth test
##### `depthFunc`
The depth detection pass function can use the following values:
- `Always`: Always pass
- `Equal`： Passed when the depth value is equal to the buffer value
- `NotEqual`：Passed when the depth value is not equal to the buffer value
- `Less`：Passed when the depth value is less than the buffer value
- `Greater`：Passed when the depth value is greater than the buffer value
- `GreaterEqual`：Pass when the depth value is greater than or equal to the buffer value
- `LessEqual`：Pass when the depth value is less than or equal to the buffer value
Associated states rendering environment configuration:
- `DisableDepthTest`： Turn off depth testing
- `DisableDepthWrite`： Turn off depth writing
#### Stencil Mask Test
##### `stencilRef`
Value to compare with or to be written to the mask buffer
##### `stencilRefOverride`
Whether to use the buffer's current value as stencilRef, 0 or 1 is supported:
- `1`： Use the configured stencilRef. If stencilRef is configured, stencilRefOverride will automatically take 1
- `0`： Use the current value of the buffer as stencilRef, in this case do not configure stencilRef
##### `stencilReadMask`
The mask buffer value and the stencilRef value are bit-ANDed with stencilReadMask before being compared
##### `stencilWriteMask`
The stencilRef value is bit-ANDed with stencilWriteMask before being written to the mask buffer
##### `frontFace` and `backFace`
Configure which mask test function to use on the front or back of the grid. In addition, the order of judgment is mask detection first, then depth detection. You need to configure the following operations:
<!-- Test if this looks ok -->
- `stencilFunc`: The method used when stencilRef is compared with the mask buffer, the following values are supported：
- `Always`: Always pass
- `Equal`： Passed when stencilRef is equal to the buffer value
- `NotEqual` ：Passed when stencilRef is not equal to the buffer value
- `Less`：Passed when stencilRef is less than the buffer value
- `Greater`：Passed when stencilRef is greater than the buffer value
- `GreaterEqual`：Passed when stencilRef is greater than or equal to the buffer value
- `LessEqual`：Passed when stencilRef is less than or equal to the buffer value
- `stencilFailOp`：The processing performed when the stencilFunc comparison function fails to return, supports the following values：
- `Keep`： Keep the original value of the buffer
- `Replace`： Writes the stencilRef bit and the value of stencilWriteMask to the buffer
- `stencilDepthFailOp` : The stencilFunc comparison function returns success, but the processing performed when the depth test fails, supports the following values：
- `Keep`： Keep the original value of the buffer
- `Replace`： Writes the stencilRef bit and the value of stencilWriteMask to the buffer
- `stencilPassOp`: The stencilFunc comparison function returns successfully, and the processing executed when the depth test is successful, supports the following values：
- `Keep`： Keep the original value of the buffer
- `Replace`： Writes the stencilRef bit and the value of stencilWriteMask to the buffer
Associated states rendering environment configuration:
- `StencilWrite`：Enable mask writing
- `EnableStencilTest`: Enable mask testing
Finally, let's look at an example:
```json
"shadow_back": {
"+states": [
"StencilWrite",
"DisableColorWrite",
"DisableDepthWrite",
"InvertCulling",
"EnableStencilTest"
],
"vertexShader": "shaders/position.vertex",
"vrGeometryShader": "shaders/position.geometry",
"fragmentShader": "shaders/flat_white.fragment",
"frontFace": {
"stencilFunc": "Always",
"stencilFailOp": "Keep",
"stencilDepthFailOp": "Keep",
"stencilPassOp": "Replace"
},
"backFace": {
"stencilFunc": "Always",
"stencilFailOp": "Keep",
"stencilDepthFailOp": "Keep",
"stencilPassOp": "Replace"
},
"stencilRef": 1,
"stencilReadMask": 255,
"stencilWriteMask": 1,
"vertexFields": [
{ "field": "Position" }
],
"msaaSupport": "Both"
}
```
In the example, StencilWrite represents the support for writing to the mask buffer, EnableStencilTest represents the opening of the mask test, and the configuration of frontFace represents that the mask test always passes when the front face is rendered. If the depth test fails, the buffer value remains unchanged. If it also passes, the stencil bit and the value of stencilWriteMask will be written to the buffer, that is, 1 & 1 = 1 value. The configuration of backFace is also similar.
#### Blend translucent object color blend
The rendering of translucent objects needs to configure the blending factor. The final output rgb color value = current color value * source blending factor + color value in buffer * destination blending factor
##### `blendSrc`
source mix factor
##### `blendDst`
target blending factor
##### `alphaSrc`
The source blending factor when calculating alpha, usually not configured to take the default value
##### `alphaDst`
The target blending factor when calculating alpha, usually not configured to take the default value
In total, the blending factor can take on the following values:
- `DestColor`： Buffer color value
- `SourceColor`： Current color value
- `Zero`： (0,0,0)
- `One`： (1,1,1)
- `OneMinusDestColor`: (1,1,1) - buffer color value
- `OneMinusSrcColor`: (1,1,1) - current color value
- `SourceAlpha`： The alpha value in the current color
- `DestAlpha`： Alpha value in buffer color
- `OneMinusSrcAlpha`： 1 - alpha value in the current color value
In the engine, the default is:
- `blendSrc`：SourceAlpha
- `blendDst`：OneMinusSrcAlpha
- `alphaSrc`：One
- `alphaDst`：OneMinusSrcAlpha
Associated states rendering environment configuration:
- `Blending`: Enables color blending mode, often used to render translucent objects. After declaring this, it is usually necessary - to declare the blending factor blendSrc, blendDst
- `DisableColorWrite`： Do not write color values to the color buffer, none of the RGBA channels are written
- `DisableAlphaWrite`： Do not write transparency alpha values to the color buffer, allow RGB values to be written
- `DisableRGBWrite`： Do not write transparency RGB values to the color buffer, allow writing alpha values
#### Sample texture sample
##### `samplerStates`
Configure the sampling state, the value is a list, and configure each texture according to the number of textures to be sampled. Usually, if UV0 and UV1 are declared in the vertex attribute, it means that two textures need to be sampled, and two elements need to be configured here. Let's look at the definition of child elements:
```json
{
"samplerIndex": 0,
"textureFilter": "Point",
"textureWrap": "Repeat"
}
```
Each property is defined as follows:
##### `samplerIndex`
Number, representing the attribute of the texture that is currently being set, starting from 0
##### `textureFilter`
Texture filtering mode (default is Point), when the actual displayed texture map is enlarged or reduced compared to the original image, the mapping relationship between the new resolution map and the pixels on the original resolution map can have the following values:
- `Point`： Point sampling
- `Bilinear`: Bilinear sampling
- `Trilinear`: Trilinear sampling
- `MipMapBilinear`： MipMap bilinear sampling
- `TexelAA`：Texel antialiasing (not supported on all devices, not recommended)
- `PCF`：Sampling by comparison function (not supported on all devices, not recommended)
##### `textureWrap`
Texture wrapping mode, which controls what kind of texture should be sampled when uv is outside [0,1]. It can have the following values:
- `Repeat`： Repeat, that is, modulo the value to [0, 1] for sampling
- `Clamp`： Edge sampling, sampling the value of the closest edge, that is, if 1.1 is closer to 1, then take 1; if -0.1 is closer to 0, then take 0.
#### Vertex
##### `vertexFields`
Vertex attributes, which are used to declare what attributes each vertex of the mesh that is rendered using this material holds. It is determined when the art is producing resources. The following values ​​may be used:
- `Position`： Model space coordinates
- `Color`： Color
- `Normal`： Normal
- `UV0`: Texture sample coordinates
- `UV1`：Texture sample coordinates
- `UV2`：Texture sample coordinates
- `BoneId0`： Bone ID, used in the bone model
#### Rasterizer environment configuration
##### `msaaSupport`
Configure MSAA (Multi-Sample Anti-Aliasing) support (the default in the engine is NonMSAA)
- `NonMSAA`: Materials are allowed when MSAA is not enabled
- `MSAA`: Materials are allowed when MSAA is enabled
- `Both`：Materials are allowed with or without MSAA enabled. Usually just use this value.
##### `depth offset`
Depth offset is mainly used to solve the z-fighting problem, that is, when two objects have similar depths, some frames may display this object and some frames display another object when rendering. The principle of depth offset is to offset one of the objects in the direction of large or small depth, so that their depths are no longer the same. The following four variables can be configured:
- depthBias
- slopeScaledDepthBias
- depthBiasOGL
- slopeScaledDepthBiasOGL
The specific offset depth is:
`offset = (slopeScaledDepthBias * m) + (depthBias * r)`
On the OGL platform it is:
`offset = (slopeScaledDepthBiasOGL * m) + (depthBiasOGL * r)`
m is the maximum value in the slope of the depth of the polygon (computed at the rasterization stage). The more parallel a polygon is to the near clipping plane, the closer m is to 0. r is the smallest value that produces a discernible difference in depth values ​​in the window coordinate system, and r is a constant specified by the platform that implements OpenGL.
Associated states rendering environment configuration:
- `Wireframe`： Draw wireframe mode
- `DisableCulling`: Render front and back simultaneously
- `InvertCulling`：Use front cropping. The default is back cropping. After declaring this, the back side is rendered and the front - side is cropped.
#### Primitive
##### `primitiveMode`
Primitive rendering mode (the default in the engine is TriangleList):
- `None`： Do not render, normally not used
- `QuadList`：Quadrilateral pattern
- `TriangleList`: A pattern of drawing a triangle every three vertices, for example the first triangle uses vertices v0, v1, v2, and the second uses v3, v4, v5
- `TriangleStrip`: Each vertex will form a triangle with the first two vertices, the structure is a bit more complicated, but it - will save the amount of data
- `LineList`: Draw a line segment every two vertices
- `Line`: Each vertex forms a line segment with a vertex that appears before it.
### Material variant
#### `variants`
Useful for quickly implementing multiple sub-materials based on most of the same definitions. See the actual example of entity_static below:
```json
"entity_static": {
"vertexShader": "shaders/entity.vertex",
"vrGeometryShader": "shaders/entity.geometry",
"fragmentShader": "shaders/entity.fragment",
"vertexFields": [
{ "field": "Position" },
{ "field": "Normal" },
{ "field": "UV0" }
],
"variants": [
{
"skinning": {
"+defines": [ "USE_SKINNING" ],
"vertexFields": [
{ "field": "Position" },
{ "field": "BoneId0" },
{ "field": "Normal" },
{ "field": "UV0" }
]
}
},
{
"skinning_color": {
"+defines": [ "USE_SKINNING", "USE_OVERLAY" ],
"+states": [ "Blending" ],
"vertexFields": [
{ "field": "Position" },
{ "field": "BoneId0" },
{ "field": "Color" },
{ "field": "Normal" },
{ "field": "UV0" }
]
}
}
],
"msaaSupport": "Both",
"+samplerStates": [
{
"samplerIndex": 0,
"textureFilter": "Point"
}
]
}
```
Variants are declarations of material variants. The above declarations declare two sub-variants, skinning and skinning_color. Some external fields are rewritten in the sub-variants. In actual use, it is equivalent to quickly defining two materials. The body and the variant are connected with a dot ".". The two materials are entity_static.skinning and entity_static.skinning_color.
In addition, if there are other materials that inherit from entity_static, such as entity_dynamic, this material will also inherit these two variants, entity_dynamic.skinning and entity_dynamic.skinning_color.
## Material Merge Rules
When the same material is declared in different directory files, it will be merged according to the following rules after loading: 1. Normally, the material fields of the files loaded later will overwrite the previously loaded ones. 2. The following fields are special. Operations to add attributes with "+" and delete attributes with "-" are supported:
- defines
- states
- samplerStates
As an example, for example, such a material is declared in the package body file (irrelevant code is omitted), and three macros are defined:
```json
"testMat": {
"defines": [ "MACRO_1", "MACRO_2", "MACRO_3" ],
}
```
At this point, a mod also declares this material, defining another three macros:
```json
"testMat": {
"defines": [ "MACRO_4", "MACRO_5", "MACRO_6" ],
}
```
In the above case, the final runtime is equivalent to the defines field being overwritten, and the macros that take effect at the actual runtime are only: MACRO_4, MACRO_5, MACRO_6
If the "+" symbol is used when defining in the MOD:
```json
"testMat": {
"+defines": [ "MACRO_4", "MACRO_5", "MACRO_6" ],
}
```
Equivalent to adding definitions on the original basis, the macros that take effect at actual runtime are: MACRO_1, MACRO_2, MACRO_3, MACRO_4, MACRO_5, MACRO_6
If the "-" symbol is used when defining in the MOD:
```json
"testMat": {
"-defines": [ "MACRO_3"],
}
```
It is equivalent to deleting some definitions on the original basis, the only macros that take effect at runtime are: MACRO_1, MACRO_2
If multiple files define the same material, and they involve overlay, add, and delete operations, the order in which they will take effect is: first perform all overlay operations, then perform all add operations, and finally perform all delete operations .
i.e. if one of the material files declares a delete MACRO_3 action:
```json
"testMat": {
"-defines": [ "MACRO_3"],
}
```
Then no matter how other files are covered, add MACRO_3, and this material must not have MACRO_3 macro after the final synthesis.

419
docs/wiki/documentation/materials.md Normal file
View File

@@ -0,0 +1,419 @@
---
title: Vanilla Materials
show_toc: false
tags:
- expert
mentions:
- SirLich
- Luthorius
- MedicalJewel105
- SmokeyStack
- ThomasOrs
---
:::warning
Materials are not for the faint of heart. Be prepared for potential crashes, content log errors, and long loading times.
:::
Materials are extremely useful for making entities more unique. You can make new ones for your addons, or use pre-existing vanilla materials.
You can learn more about creating materials [here](/visuals/materials).
## List of Vanilla Materials
| Vanilla_Material |
| --------------------------------------------------------------------------------------- |
| [alpha_block](#alpha-block) |
| [alpha_block_color](#alpha-block-color) |
| [banner](#banner) |
| [banner_pole](#banner-pole) |
| [beacon_beam](#beacon-beam) |
| [beacon_beam_transparent](#beacon-beam-transparent) |
| [charged_creeper](#charged-creeper) |
| [conduit_wind](#conduit-wind) |
| [entity](#entity) |
| [entity_alphablend](#entity-alphablend) |
| [entity_alphablend_nocolorentity_static](#entity-alphablend-nocolorentity-static) |
| [entity_alphatest](#entity-alphatest) |
| [entity_alphatest_change_color](#entity-alphatest-change-color) |
| [entity_alphatest_change_color_glint](#entity-alphatest-change-color-glint) |
| [entity_alphatest_glint](#entity-alphatest-glint) |
| [entity_alphatest_glint_item](#entity-alphatest-glint-item) |
| [entity_alphatest_multicolor_tint](#entity-alphatest-multicolor-tint) |
| [entity_beam](#entity-beam) |
| [entity_beam_additive](#entity-beam-additive) |
| [entity_change_color](#entity-change-color) |
| [entity_change_color_glint](#entity-change-color-glint) |
| [entity_custom](#entity-custom) |
| [entity_dissolve_layer0](#entity-dissolve-layer0) |
| [entity_dissolve_layer1](#entity-dissolve-layer1) |
| [entity_emissive](#entity-emissive) |
| [entity_emissive_alpha](#entity-emissive-alpha) |
| [entity_emissive_alpha_one_sided](#entity-emissive-alpha-one-sided) |
| [entity_flat_color_line](#entity-flat-color-line) |
| [entity_glint](#entity-glint) |
| [entity_lead_base](#entity-lead-base) |
| [entity_loyalty_rope](#entity-loyalty-rope) |
| [entity_multitexture](#entity-multitexture) |
| [entity_multitexture_alpha_test](#entity-multitexture-alpha-test) |
| [entity_multitexture_alpha_test_color_mask](#entity-multitexture-alpha-test-color-mask) |
| [entity_multitexture_color_mask](#entity-multitexture-color-mask) |
| [entity_multitexture_masked](#entity-multitexture-masked) |
| [entity_multitexture_multiplicative_blend](#entity-multitexture-multiplicative-blend) |
| [entity_nocull](#entity-nocull) |
| [guardian_ghost](#guardian-ghost) |
| [item_in_hand](#item-in-hand) |
| [item_in_hand_entity_alphatest](#item-in-hand-entity-alphatest) |
| [item_in_hand_entity_alphatest_color](#item-in-hand-entity-alphatest-color) |
| [item_in_hand_glint](#item-in-hand-glint) |
| [item_in_hand_multicolor_tint](#item-in-hand-multicolor-tint) |
| [map](#map) |
| [map_decoration](#map-decoration) |
| [map_marker](#map-marker) |
| [moving_block](#moving-block) |
| [moving_block_alpha](#moving-block-alpha) |
| [moving_block_alpha_seasons](#moving-block-alpha-seasons) |
| [moving_block_alpha_single_side](#moving-block-alpha-single-side) |
| [moving_block_blend](#moving-block-blend) |
| [moving_block_double_side](#moving-block-double-side) |
| [moving_block_seasons](#moving-block-seasons) |
| [opaque_block](#opaque-block) |
| [opaque_block_color](#opaque-block-color) |
| [opaque_block_color_uv2](#opaque-block-color-uv2) |
## Properties
Materials can have a range of different properties which affect their appearance, including:
### Backface-Culling
This makes the inside faces of models **not** render.
### Alpha Channel
Enables analogue translucency, usage of the alpha channel of textures.
### Emissive
Causes the texture to not be affected by dim lighting, and appear to glow. If there is usage of the alpha channel, the emissivity is in direct proportion to how transparent each individual pixel is.
### Set Translucency
Regardless of other properties, is always completely rendered at a pre-determined translucency.
### Texture Blending
When multiple textures are present, may use a filter of sorts to change the entities appearance, based on the textures.
## Details on the Materials
The following is a last of each material, along with general known properties. The names are vague pointers to what each will do, some may act rather unpredictably, or have undocumented usages, so this only is what's certain for each:
:::warning
The following section has currently **only** been tested for with single textures. Take it all with a pinch of salt. It is highly recommended to experiment with the materials yourself.
:::
### alpha_block
- Backface-culling
- Completely Opaque
### alpha_block_color
- Backface-Culling
- Translucencies as Transparent
### banner
Inconsistently renders objects with transparency behind.
- N/A
### banner_pole
Inconsistently renders objects with transparency behind.
- Backface-Culling
- Transparency
### beacon_beam
- Completely Opaque
### beacon_beam_transparent
This one is rather different. Particles that are behind it are rendered in front, and it appears to have "Frontface-Culling".
- Alpha Channel
### charged_creeper
Inconsistently renders objects with transparency behind.
- Emissive
- Set Translucency
### conduit_wind
- Transparency
- Translucency as Transparency
### entity
- Completely Opaque
- Backface Culling
### entity_alphablend
Inconsistently renders objects with transparency behind.
- Backface-Culling
- Alpha Channel
### entity_alphablend_nocolorentity_static
- Unknown
- Potential Crash
### entity_alphatest
- Transparency
- Translucency as Transparency
### entity_alphatest_change_color
- Transparency
- Translucency as Opaque
### entity_alphatest_change_color_glint
- Unknown
### entity_alphatest_glint
- Unknown
### entity_alphatest_glint_item
- Unknown
### entity_alphatest_multicolor_tint
- Greyscale
- Backface-Culling
- Transparency
- Translucency as Opaque
### entity_beam
- Transparency
- Translucency as Transparency
### entity_beam_additive
Particles always render on top
- Transparency
- Emissive
- Backface-Culling
- Set Translucency
### entity_change_color
- Completely Opaque
### entity_change_color_glint
- Unknown
### entity_custom
Inconsistently renders objects with transparency behind.
- Backface-Culling
- Alpha Channel
### entity_dissolve_layer0
Inconsistently renders objects with transparency behind.
- Unknown
### entity_dissolve_layer1
- Unknown
### entity_emissive
- Emissive
- Completely Opaque
- Backface-Culling
### entity_emissive_alpha
- Emissive
- Alpha Channel
- Transparency
### entity_emissive_alpha_one_sided
- Emissive
- Alpha Channel
- Transparency
- Backface-Culling
### entity_flat_color_line
- Backface-Culling
- Completely Opaque
### entity_glint
- Unknown
### entity_lead_base
Inconsistently renders objects with transparency behind.
- Alpha Channel
### entity_loyalty_rope
- Unknown
### entity_multitexture
- Unknown
### entity_multitexture_alpha_test
- Unknown
### entity_multitexture_alpha_test_color_mask
- Unknown
### entity_multitexture_color_mask
- Unknown
### entity_multitexture_masked
- Unknown
### entity_multitexture_multiplicative_blend
- Unknown
### entity_nocull
- Completely Opaque
### guardian_ghost
Inconsistently renders objects with transparency behind.
- Backface-Culling
- Alpha Channel
### item_in_hand
- Completely Opaque
- Backface-Culling
### item_in_hand_entity_alphatest
- Transparency
- Translucency into either Opaque or Transparent depends on level.
### item_in_hand_entity_alphatest_color
- Transparency
- Translucency into either Opaque or Transparent depends on level.
### item_in_hand_glint
- Unknown
### item_in_hand_multicolor_tint
- Greyscale
- Completely Opaque
- Backface-Culling
### map
- Transparency
- Translucency into either Opaque or Transparent depends on level.
### map_decoration
- Backface-Culling
- Transparency
- Translucency into either Opaque or Transparent depends on level.
### map_marker
- Backface-Culling
- Transparency
- Translucency into either Opaque or Transparent depends on level.
- Potential Crash
### moving_block
- Completely Opaque
- Backface-Culling
### moving_block_alpha
- Backface-Culling
- Transparency
- Translucency into either Opaque or Transparent depends on level.
### moving_block_alpha_seasons
- Translucency into either Opaque or Transparent depends on level.
- Transparency
### moving_block_alpha_single_side
- Backface-Culling
- Transparency
- Translucency into either Opaque or Transparent depends on level.
### moving_block_blend
Inconsistently renders objects with transparency behind.
- Backface-Culling
- Alpha Channel
### moving_block_double_side
- Completely Opaque
### moving_block_seasons
- Completely Opaque
- Backface-Culling
### opaque_block
- Completely Opaque
- Backface-Culling
### opaque_block_color
- Completely Opaque
- Backface-Culling
### opaque_block_color_uv2
- Completely Opaque
- Backface-Culling
:::warning
Please note, that these have also only been tested using a RenderDragon platform. Non-RenderDragon visuals may differ.
:::

113
docs/wiki/documentation/pack-structure.md Normal file
View File

@@ -0,0 +1,113 @@
---
title: Pack Folder Structure
show_toc: false
mentions:
- SirLich
- ThijsHankelMC
- MedicalJewel105
- Esatz77
- ChibiMango
- TheItsNameless
- JaylyDev
- SmokeyStack
---
<FolderView :paths="[
'BP/manifest.json',
'BP/pack_icon.png',
'BP/animations/example.animation.json',
'BP/animation_controllers/example.ac.json',
'BP/blocks/example.block.json',
'BP/biomes/example.biome.json',
'BP/entities/example.se.json',
'BP/features/example.feature.json',
'BP/feature_rules/example.rule.json',
'BP/functions/example.mcfunction',
'BP/functions/tick.json',
'BP/items/example.item.json',
'BP/loot_tables/example.loot.json',
'BP/recipes/example.recipe.json',
'BP/scripts/client/exampleClient.js',
'BP/scripts/server/exampleServer.js',
'BP/scripts/exampleScript.js',
'BP/spawn_rules/example.spawn.json',
'BP/texts/languages.json',
'BP/texts/\*.lang',
'BP/trading/example.trade.json',
'BP/trading/economy_trades/example.trade.json',
'BP/structures/example.mcstructure',
'RP/manifest.json',
'RP/pack_icon.png',
'RP/biomes_client.json',
'RP/blocks.json',
'RP/sounds.json',
'RP/contents.json',
'RP/animation_controllers/example.ac.json',
'RP/animations/example.animation.json',
'RP/attachables/example.attachable.json',
'RP/entity/example.ce.json',
'RP/fogs/example_fog_setting.json',
'RP/items/example.item.json',
'RP/materials/example.material',
'RP/models/entity/example.geo.json',
'RP/models/blocks/example.geo.json',
'RP/particles/example.particle.json',
'RP/render_controllers/example.rc.json',
'RP/sounds/example.wav',
'RP/sounds/example.ogg',
'RP/sounds/example.mp3',
'RP/sounds/example.fsb',
'RP/sounds/sound_definitions.json',
'RP/sounds/music_definitions.json',
'RP/texts/languages.json',
'RP/texts/language_names.json',
'RP/texts/bg_BG.lang',
'RP/texts/cs_CZ.lang',
'RP/texts/da_DK.lang',
'RP/texts/de_DE.lang',
'RP/texts/el_GR.lang',
'RP/texts/en_GB.lang',
'RP/texts/en_US.lang',
'RP/texts/es_ES.lang',
'RP/texts/es_MX.lang',
'RP/texts/fi_FI.lang',
'RP/texts/fr_CA.lang',
'RP/texts/fr_FR.lang',
'RP/texts/hu_HU.lang',
'RP/texts/id_ID.lang',
'RP/texts/it_IT.lang',
'RP/texts/ja_JP.lang',
'RP/texts/ko_KR.lang',
'RP/texts/nb_NO.lang',
'RP/texts/nl_NL.lang',
'RP/texts/pl_PL.lang',
'RP/texts/pt_BR.lang',
'RP/texts/pt_PR.lang',
'RP/texts/ru_RU.lang',
'RP/texts/sk_SK.lang',
'RP/texts/sv_SE.lang',
'RP/texts/tr_TR.lang',
'RP/texts/uk_UA.lang',
'RP/texts/zh_CN.lang',
'RP/texts/zh_TW.lang',
'RP/texts/zh_TW.lang',
'RP/texts/ja_JP/font/glyph_2E.png',
'RP/texts/ja_JP/font/\*.png',
'RP/texts/zh_TW/font/glyph_2E.png',
'RP/texts/zh_TW/font/\*.png',
'RP/textures/item_texture.json',
'RP/textures/terrain_texture.json',
'RP/textures/flipbook_textures.json',
'RP/textures/texture_list.json',
'RP/textures/environment/overworld_cubemap/cubemap_0.png',
'RP/textures/environment/overworld_cubemap/cubemap_1.png',
'RP/textures/environment/overworld_cubemap/cubemap_2.png',
'RP/textures/environment/overworld_cubemap/cubemap_3.png',
'RP/textures/environment/overworld_cubemap/cubemap_4.png',
'RP/textures/environment/overworld_cubemap/cubemap_5.png',
'RP/textures/blocks/example.png',
'RP/textures/entity/example.png',
'RP/textures/items/example.png',
'RP/textures/particle/example.png',
'RP/ui/\*.json'
]"></FolderView>

256
docs/wiki/documentation/projectiles.md Normal file
View File

@@ -0,0 +1,256 @@
---
title: Projectiles
mentions:
- SirLich
- stirante
- retr0cube
- SmokeyStack
- Luthorius
- ThomasOrs
---
## Overview
This page intends to document all different fields you can use inside `minecraft:projectile` entity behavior component.
:::warning
_Disclaimer: this component has been mostly documented based on projectiles found in the game or reverse engineering the game._
_This information was last tested on **1.18.2**._
:::
| Name | Type | Default Value | Description |
| ------------------------- | ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| anchor | Integer | | |
| angle_offset | Decimal | 0 | Determines the angle at which the projectile is thrown |
| catch_fire | Boolean | false | If true, the entity hit will be set on fire |
| crit_particle_on_hurt | Boolean | false | If true, the projectile will produce critical hit particles when it happens |
| destroy_on_hurt | Boolean | false | If true, this entity will be destroyed when hit |
| filter | String | | Entity Definitions defined here can't be hurt by the projectile |
| fire_affected_by_griefing | Boolean | false | If true, whether the projectile causes fire is affected by the mob griefing game rule |
| gravity | Decimal | 0.05 | The gravity applied to this entity when thrown. The higher the value, the faster the entity falls |
| hit_ground_sound | String | | The sound that plays when the projectile hits ground |
| hit_sound | String | | The sound that plays when the projectile hits an entity |
| homing | Boolean | false | If true, the projectile homes in to the nearest. **Does not work on 1.18.2** entity |
| inertia | Decimal | 0.99 | The fraction of the projectile's speed maintained every frame while traveling in air |
| is_dangerous | Boolean | false | If true, the projectile will be treated as dangerous to the players |
| knockback | Boolean | true | If true, the projectile will knock back the entity it hits |
| lightning | Boolean | false | If true, the entity hit will be struck by lightning |
| liquid_inertia | Decimal | 0.6 | The fraction of the projectile's speed maintained every frame while traveling in water |
| multiple_targets | Boolean | true | If true, the projectile can hit multiple entities per flight |
| offset | Vector [a, b, c] | [0, 0.5, 0] | The offset from the entity's anchor where the projectile will spawn |
| on_fire_time | Decimal | 5 | Time in seconds that the entity hit will be on fire for |
| on_hit | Object | | Projectile's behavior on hit. More info [below](#on_hit) |
| particle | String | iconcrack | Particle to use upon collision |
| potion_effect | Integer | -1 | Defines the effect the arrow will apply to the entity it hits |
| power | Decimal | 1.3 | Determines the velocity of the projectile |
| reflect_on_hurt | Boolean | false | If true, this entity will be reflected back when hit |
| semi_random_diff_damage | Boolean | false | If true, damage will be randomized based on damage and speed |
| shoot_sound | String | | The sound that plays when the projectile is shot |
| shoot_target | Boolean | true | If true, the projectile will be shot towards the target of the entity firing it |
| should_bounce | Boolean | false | If true, the projectile will bounce upon hit |
| splash_potion | Boolean | false | If true, the projectile will be treated like a splash potion |
| splash_range | Decimal | 4 | Radius in blocks of the 'splash' effect |
| stop_on_hurt | Boolean | | |
| uncertainty_base | Decimal | 0 | The base accuracy. Accuracy is determined by the formula uncertaintyBase - difficultyLevel \* uncertaintyMultiplier |
| uncertainty_multiplier | Decimal | 0 | Determines how much difficulty affects accuracy. Accuracy is determined by the formula uncertaintyBase - difficultyLevel \* uncertaintyMultiplier |
| hit_water | Boolean | false | If true, liquid blocks will be treated as solid. **Requires "Education Edition" toggle active** |
## on_hit
This object contains all behaviors, that can be executed, when projectile hits something.
### arrow_effect
_Exact behavior unknown_
### teleport_owner
Teleports shooter to the hit location.
### catch_fire
_Exact behavior unknown_
Sets target on fire
### ignite
_Exact behavior unknown_
Sets target on fire
### remove_on_hit
Removes the projectile when it hits something.
### douse_fire
_Exact behavior unknown_
### impact_damage
Deals damage on hit.
| Name | Type | Description |
| ------------------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| damage | Integer/Integer Array [min, max] | Damage dealt to entity on hit |
| semi_random_diff_damage | Boolean | |
| max_critical_damage | Decimal | |
| min_critical_damage | Decimal | |
| power_multiplier | Decimal | |
| channeling | Boolean | |
| set_last_hurt_requires_damage | Boolean | |
| destroy_on_hit_requires_damage | Boolean | |
| filter | String | Entity to affect. Much more primitive than filters used elsewhere, as it cannot "test" for anything other than an identifier |
| destroy_on_hit | Boolean | |
| knockback | Boolean | |
| catch_fire | Boolean | Dictates wether or not targets will be engulfed in flames |
### definition_event
Calls an event on hit.
| Name | Type | Description |
| ------------------ | ------- | --------------------------------------------------- |
| affect_projectile | Boolean | Event will be triggered for projectile entity |
| affect_shooter | Boolean | Event will be triggered for shooter entity |
| affect_target | Boolean | Event will be triggered for hit entity |
| affect_splash_area | Boolean | Event will be triggered for all entities in an area |
| splash_area | Decimal | Area of entities |
| event_trigger | Object | Event to trigger. Structure below. |
| Name | Type | Description |
| ------- | ------ | ------------------------------------- |
| event | String | Event to trigger |
| target | String | Target of the event |
| filters | Object | Criteria required in order to trigger |
### stick_in_ground
Sticks the projectile into the ground.
| Name | Type | Description |
| ---------- | ------- | ----------- |
| shake_time | Decimal | |
### spawn_aoe_cloud
Spawns an area of effect cloud of potion effect.
| Name | Type | Description |
| ------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| radius | Decimal | Radius of the cloud |
| radius_on_use | Decimal | |
| potion | Integer | Lingering Potion ID |
| particle | String | [Vanilla Particles](/particles/vanilla-particles) emitter of the cloud. Only accepts Vanilla Particles. **dragonbreath** enables the usage of Bottles to obtain Dragon's Breath. |
| duration | Integer | Duration of the cloud in seconds |
| color | Integer array [r, g, b] | Color of the particles |
| affect_owner | Boolean | Is potion effect affecting the shooter. Does not appear to apply to the player |
| reapplication_delay | Integer | Delay in ticks between application of the potion effect |
#### Potion IDs
| Potion | Regular | Extended | Enhanced (Level II) |
| ------------------------- | ------- | -------- | ------------------- |
| Water Bottle | 0 | | |
| Mundane Potion | 1 | 2 | |
| Thick Potion | 3 | | |
| Awkward Potion | 4 | | |
| Potion of Night Vision | 5 | 6 | |
| Potion of Invisibility | 7 | 8 | |
| Potion of Leaping | 9 | 10 | 11 |
| Potion of Fire Resistance | 12 | 13 | |
| Potion of Swiftness | 14 | 15 | 16 |
| Potion of Slowness | 17 | 18 | |
| Potion of Water Breathing | 19 | 20 | |
| Potion of Healing | 21 | | 22 |
| Potion of Harming | 23 | | 24 |
| Potion of Poison | 25 | 26 | 27 |
| Potion of Regeneration | 28 | 29 | 30 |
| Potion of Strength | 31 | 32 | 33 |
| Potion of Weakness | 34 | 35 | |
| Potion of Decay | 36 | | |
| Potion of Turtle Master | 37 | 38 | 39 |
| Potion of Slow Falling | 40 | 41 | |
| Potion of Slowness IV | 42 | | |
| Potion of Crashing | 43+ | | |
### spawn_chance
Spawns an entity on hit.
| Name | Type | Description |
| --------------------------- | ------- | ------------------------------------------- |
| first_spawn_percent_chance | Decimal | |
| second_spawn_percent_chance | Decimal | |
| first_spawn_count | Integer | |
| second_spawn_count | Integer | |
| spawn_definition | String | ID of the entity to spawn |
| spawn_baby | Boolean | Whether the spawned entity should be a baby |
### particle_on_hit
Spawns particles on hit.
| Name | Type | Description |
| ------------- | ------- | -------------------------------------------------------- |
| particle_type | String | [Vanilla Particles](/particles/vanilla-particles) to use |
| num_particles | Integer | Number of particles |
| on_entity_hit | Boolean | Whether it should spawn particles on entity hit |
| on_other_hit | Boolean | Whether it should spawn particles on other hit |
### mob_effect
Applies a mob effect to the target.
| Name | Type | Description |
| -------------- | ------- | ------------------------------------------- |
| effect | String | Effect |
| duration | Integer | Duration of the effect |
| durationeasy | Integer | Duration of the effect on easy difficulty |
| durationnormal | Integer | Duration of the effect on normal difficulty |
| durationhard | Integer | Duration of the effect on hard difficulty |
| amplifier | Integer | Effect amplifier |
| ambient | Boolean | |
| visible | Boolean | |
### grant_xp
Despite the name, this actually spawns a number of experience orbs, being worth the amount stated.
| Name | Type | Description |
| ----- | ------- | ----------------------------------------------------------------------------------------------- |
| minXP | Integer | Minimum amount of experience to give |
| maxXP | Integer | Maximum amount of experience to give |
| xp | Integer | Constant amount of experience to give. When set, it will be used instead of min and max values. |
### freeze_on_hit
_Exact behavior unknown_
_Requires Education Edition toggle to be enabled._
Freezes water on hit.
| Name | Type | Description |
| ------------- | ------- | ----------------------------- |
| shape | String | "sphere" or "cube" |
| snap_to_block | Boolean | |
| size | Integer | The size of the freeze effect |
### hurt_owner
_Exact behavior unknown. Right now it crashes minecraft probably because of wrong parameters_
| Name | Type | Description |
| ------------ | ------- | ----------- |
| owner_damage | Integer | |
| knockback | Boolean | |
| ignite | Boolean | |
### thrown_potion_effect
_Exact behavior unknown. Right now it crashes minecraft probably because it's only valid for thrown potions_
## Additional Information
When it comes to creating a custom projectile, such as an arrow or trident variant, or something entirely your own, you may want to consider defining a [runtime identifier](/entities/runtime-identifier) to ensure that it acts as intended. Not doing so may result in unintended behaviour, from odd visuals to incorrect knockback direction and arrows that you can kill with your bare hands.

567
docs/wiki/documentation/queries.md Normal file
View File

@@ -0,0 +1,567 @@
---
title: Molang Queries
toc_max_level: 2
mentions:
- SirLich
- solvedDev
- stirante
- SmokeyStack
- Dreamedc2015
- Ultr4Anubis
- MedicalJewel105
- TreaBeane
- r4isen1920
- ChillRx
- Luthorius
- TheItsNameless
- ThomasOrs
---
The bedrock documentation for Molang is notoriously bad. This page will attempt to remedy this by providing additional details for individual queries, _where possible_. This page is intended to be searched, not read in full. Use the side-bar, or use `ctrl-f` to navigate.
:::tip
This page is not an exhaustive list list! It only contains queries we've written extra information for. The full list of queries can be found [here](https://bedrock.dev/docs/stable/Molang#List%20of%20Entity%20Queries)!
:::
## query.armor_texture_slot
Formatted like: `query.armor_texture_slot(x) = y`.
Where `x` and `y` are both integer arguments, from the following table:
### X
| Argument | Slot |
| -------- | ---------- |
| 0 | Helmet |
| 1 | Chestplace |
| 2 | Leggings |
| 3 | Boots |
### Y
| Argument | Type |
| -------- | --------------------- |
| -1 | none |
| 0 | Leather armor piece |
| 1 | Chain armor piece |
| 2 | Iron armor piece |
| 3 | Diamond armor piece |
| 4 | Gold armor piece |
| 5 | Elytra |
| 6 | Turtle helmet |
| 7 | Netherite armor piece |
### Y for horses
| Argument | Type |
| -------- | --------------------- |
| 1 | Leather armor piece |
| 2 | Iron armor piece |
| 3 | Gold armor piece |
| 4 | Diamond armor piece |
### Example
`query.armor_texture_slot(3) == 1`: queries for Iron Boots.
## query.armor_material_slot
Formatted like: `query.armor_material_slot(x) = y`.
Where `x` and `y` are both integer arguments, from the following table:
### X
| Argument | Slot |
| -------- | ---------- |
| 0 | Helmet |
| 1 | Chestplace |
| 2 | Leggings |
| 3 | Boots |
### Y
Unknown, possibly:
| Argument | Slot |
| -------- | -------------------------- |
| 0 | Default armor material |
| 1 | Enchanted armor material |
| 2 | Leather armor material |
| 3 | Leather enchanted material |
## query.armor_color_slot
_Notice: As of version `1.16.100.51`, this query is crashing minecraft. It might be fixed in later versions._
Formatted like: `color = query.armor_color_slot(slot, channel)`.
Where `slot` and `channel` are both integer arguments, from the following tables:
### Slot
| Argument | Slot |
| -------- | ---------- |
| 0 | Helmet |
| 1 | Chestplace |
| 2 | Leggings |
| 3 | Boots |
### Channel
| Argument | Slot |
| -------- | ------------- |
| 0 | Red channel |
| 1 | Green channel |
| 2 | Blue channel |
| 3 | Alpha channel |
### Color
Query returns color value in specified channel.
## query.get_equipped_item_name
:::warning
**DEPRECATED QUERY:** It is recommended to use the new query (`query.is_item_name_any`) if possible as it is more of an updated version of this query. However, this query will still continue to work in the future for backwards compatibility.
:::
Formatted like: `query.get_equipped_item_name('main_hand') = 'item_name'`
Takes one optional hand slot as a parameter (0 or 'main_hand' for main hand, 1 or 'off_hand' for off hand), and a second parameter (0=default) if you would like the equipped item or any non-zero number for the currently rendered item, and returns the name of the item in the requested slot (defaulting to the main hand if no parameter is supplied) if there is one, otherwise returns ''.
Where `item_name` is the item you want to test for. No namespace, and please notice the quotes.
Example: `"query.get_equipped_item_name == 'diamond'"`
**Can you test for items in the inventory? Yes! Using the new query `query.is_item_name_any`.**
## query.get_name
:::warning
**DEPRECATED QUERY:** It is recommended to use the new query (`query.is_name_any`) if possible as it is more of an updated version of this query. However, this query will still continue to work in the future for backwards compatibility.
:::
Formatted like: `query.get_name == 'Name'`
Turns true if actual in-game displayed name matches name (use OnixClient to see names in third view).
Needs to be used in special conditions.
<Spoiler title="Show">
<CodeHeader>animation_controllers/ac.json</CodeHeader>
```json
{
"format_version": "1.10.0",
"animation_controllers": {
"controller.animation.ac": {
"initial_state": "default",
"states": {
"default": {
"transitions": [
{
"active": "query.is_alive"
}
]
},
"active": {
"transitions": [
{
"default": "(1.0)"
}
],
"animations": [
{
"anim": "query.get_name == '...'" // You can use it only here!
}
]
}
}
}
}
}
```
</Spoiler>
## query.is_name_any
Formatted like: `query.get_name('Name1', 'Name2')`.
Takes one or more arguments.
Turns true if actual in-game displayed name matches one of the given names.
Needs to be used in special conditions.
<Spoiler title="Show">
<CodeHeader>animation_controllers/ac.json</CodeHeader>
```json
{
"format_version": "1.10.0",
"animation_controllers": {
"controller.animation.ac": {
"initial_state": "default",
"states": {
"default": {
"transitions": [
{
"active": "query.is_alive"
}
]
},
"active": {
"transitions": [
{
"default": "(1.0)"
}
],
"animations": [
{
"anim": "query.is_name_any(...)" // You can use it only here!
}
]
}
}
}
}
}
```
</Spoiler>
## query.is_item_name_any
Formatted like: `query.is_item_name_any('slot.weapon.mainhand', 0, 'namespace:item_name')`
Takes the equipment slot name first, followed by the slot index value, and then the list of item names with namespaces after it.
Possible equipment slot are as follows:
| Slot Name | Slot Counts | Description |
| ---------------------- | ----------- | ----------------------------------------------------------------------------------- |
| `slot.weapon.mainhand` | 0 | Usually any held items are in here |
| `slot.weapon.offhand` | 0 | Offhand slot for things like `Shield`, `Totem of Undying` or a `Map` |
| `slot.armor.head` | 0 | Head armor piece |
| `slot.armor.chest` | 0 | Chestplate armor piece |
| `slot.armor.legs` | 0 | Leggings armor piece |
| `slot.armor.feet` | 0 | Boots armor piece |
| `slot.armor` | 0 | Horse armor |
| `slot.saddle` | 0 | Saddle slot |
| `slot.hotbar` | 0 to 8 | Player hotbar slots |
| `slot.inventory` | 0+ (varies) | Entities that has an inventory, like the player, minecart with chests, donkey, etc. |
| `slot.enderchest` | 0 to 26 | Ender chest inventory for players only |
### Test for items within the player's inventory
Formatted like: `t.val = 0; t.i = 0; loop(27, {t.val = q.is_item_name_any('slot.inventory', t.i, 'namespace:item_name'); t.val ? {return t.val;}; t.i = t.i+1;});`
Replace `namespace:item_name` with any item you wish to check for. This simply loops through all 27 slots of the inventory and returns `1.0` if it has found any slot that has the specified item provided. Note that the hotbar is in a different slot from the main inventory slot so you will have to check that separately.
## query.is_enchanted
Formatted like: `is_enchanted = query.is_enchanted`.
Return 1.0 or 0.0 based on whether the entity is enchanted.
_Currently, can be only used in materials._
## query.is_eating
This query tracks when certain entities are 'eating'. It's not used for the player. To trigger, use one of the following components:
- `minecraft:behavior.eat_carried_item`
- `minecraft:behavior.snacking`
## query.is_ghost
Formatted like: `is_ghost = query.is_ghost`.
Return 1.0 or 0.0 based on whether the entity is a ghost.
_Currently, only returns 1.0 for a guardian ghost and is used by its renderer._
## query.is_grazing
Formatted like: `is_grazing = query.is_grazing`.
Return 1.0 or 0.0 based on whether the entity is eating a block.
_Currently, only returns 1.0 for a sheep and entities using runtime identifier of a sheep._
## query.is_jumping
Formatted like: `is_jumping = query.is_jumping`.
Return 1.0 or 0.0 based on whether the entity is jumping.
For the player, conditions for its activation are:
- the jump button is pressed (includes being in water and climbing a scaffolding)
- OR auto-jump is triggered
- OR swimming with auto-jump
- OR charging the jump of a ridable entity
## query.modified_move_speed
Formatted like: `modified_move_speed = query.modified_move_speed`.
Returns the current walk speed of the entity modified by status flags such as is_baby or on_fire
Value example:
- Player is walking: around 0.86
- Player is sprinting: 1.0
- Player is sprinting and jumping: 0.35
- Player is walking on fire: 1.0
- Player is sprinting on fire: 1.0
- Player is sprinting and jumping on fire: 0.525
## query.log
Content log is NOT debug log, they're different files. `query.log` outputs to the debug log only.
## query.on_fire_time
Formatted like: `on_fire_time = query.on_fire_time`.
Returns the time in ticks since the entity started or stopped being on fire, else it returns 0.0
Value example:
- Entity is summoned: value is 0
- Entity is ignited: value is 0 and starts counting up 1 every tick
- Entity is on fire for 2 seconds already: value is 40 and still counts up 1 every tick
- Entity stops being on fire: value resets to 0 and continues to count up 1 every tick despite not being on fire
- Entity is ignited second time: value resets to 0 and continues counting up 1 every tick
- Entity stops being on fire the second time: value resets to 0 and continues to count up 1 every tick despite not being on fire
Basically it's tick timer that starts after entity is first ignited and resets every time it changes from/to being on fire.
## query.scoreboard
Formatted like: `query.scoreboard('objective_name') > 0`
Returns 1.0 or 0.0 if the queried value is within the specified range provided. Or based on score count, molang operator and number.
Note that sometimes it might not work because of unknown reasons. One of which is that this cannot query scoreboard objective names with uppercase letters. In this case, for example, objective `testfoo` will work but **not** `testFoo`.
## query.structural_integrity
Formatted like: `structural_integrity = query.structural_integrity`.
Used by boats and minecarts for destroying it. It will decrease when attacking the entity and will recover with time.
Probably unusable by anything other than boats and minecarts.
## variable.attack_time
### Explanation
This variable is setup as IF it was a query. In other words, it can be used on any entity, both on the client and server, regardless of whether you setup/define the variable correctly.
### For entities
The variable tracks when the entity is swinging to attack. When not attacking, it will return 0.0, when attacking it will range from 0.0 to the total attack time, which may be around 0.3 or something similar. For players, this value ranges from 0.0 to 1.0. The variable returns a percentage, in the form of a decimal, for how far into the attack the entity is. For example, if an entity is halfway into its attack swing, then the variable will return 0.5. It increments linearly.
### For the Player
For the player, the variable will track whenever the arm bones are swinging, this includes:
- placing blocks
- placing entities
- interacting (when swing is enabled)
- melee attack
## query.is_roaring
Evaluates to true when a `knockback_roar` attack is happening.
## query.head_x_rotation
Formatted like: `query.head_x_rotation(x)`
Where `x` specifies the head of the entity. It is not really relevant for any entity but the wither.
Returns head pitch. looking up returns `-89.9`, looking all the way down returns `89.9`.
## query.head_y_rotation
Formatted like: `query.head_y_rotation(x)`
Where `x` specifies the head of the entity. It is not really relevant for any entity but the wither.
Returns yaw of the head from `-179.9` to `179.9`. the values wrap around so like if you are at `-179.9` and you turn just a little bit, it instantly goes to `179.9`.
## query.target_x_rotation and query.target_y_rotation
Identical to the respective `query.head_*_rotation`, however has no optional argument for selecting head.
## query.time_of_day
Returns the time of day (midnight=0.0, sunrise=0.25, noon=0.5, sunset=0.75) of the dimension the entity is in.
Day time is calculated via this formula:
`f(x) = (x*0.25/2400)mod 1`
query.time_of_day - day time table
<Spoiler title="Show">
| `query.time_of_day` | Day Time |
| ------------------- | -------- |
| 0.00 | 18000 |
| 0.01 | 18240 |
| 0.02 | 18480 |
| 0.03 | 18720 |
| 0.04 | 18960 |
| 0.05 | 19200 |
| 0.06 | 19440 |
| 0.07 | 19680 |
| 0.08 | 19920 |
| 0.09 | 20162 |
| 0.10 | 20400 |
| 0.11 | 20640 |
| 0.12 | 20880 |
| 0.13 | 21120 |
| 0.14 | 21360 |
| 0.15 | 21602 |
| 0.16 | 21840 |
| 0.17 | 22080 |
| 0.18 | 22322 |
| 0.19 | 22560 |
| 0.20 | 22800 |
| 0.21 | 23040 |
| 0.22 | 23280 |
| 0.23 | 23520 |
| 0.24 | 23760 |
| 0.25 | 0 |
| 0.26 | 240 |
| 0.27 | 480 |
| 0.28 | 720 |
| 0.29 | 960 |
| 0.30 | 1202 |
| 0.31 | 1440 |
| 0.32 | 1680 |
| 0.33 | 1922 |
| 0.34 | 2160 |
| 0.35 | 2400 |
| 0.36 | 2642 |
| 0.37 | 2880 |
| 0.38 | 3120 |
| 0.39 | 3360 |
| 0.40 | 3600 |
| 0.41 | 3840 |
| 0.42 | 4080 |
| 0.43 | 4320 |
| 0.44 | 4560 |
| 0.45 | 4800 |
| 0.46 | 5040 |
| 0.47 | 5280 |
| 0.48 | 5520 |
| 0.49 | 5760 |
| 0.50 | 6000 |
| 0.51 | 6240 |
| 0.52 | 6480 |
| 0.53 | 6720 |
| 0.54 | 6960 |
| 0.55 | 7200 |
| 0.56 | 7440 |
| 0.57 | 7680 |
| 0.58 | 7920 |
| 0.59 | 8160 |
| 0.60 | 8402 |
| 0.61 | 8640 |
| 0.62 | 8880 |
| 0.63 | 9120 |
| 0.64 | 9360 |
| 0.65 | 9600 |
| 0.66 | 9842 |
| 0.67 | 10080 |
| 0.68 | 10320 |
| 0.69 | 10560 |
| 0.70 | 10800 |
| 0.71 | 11040 |
| 0.72 | 11282 |
| 0.73 | 11520 |
| 0.74 | 11760 |
| 0.75 | 12000 |
| 0.76 | 12240 |
| 0.77 | 12480 |
| 0.78 | 12720 |
| 0.79 | 12962 |
| 0.80 | 13200 |
| 0.81 | 13440 |
| 0.82 | 13680 |
| 0.83 | 13920 |
| 0.84 | 14160 |
| 0.85 | 14402 |
| 0.86 | 14640 |
| 0.87 | 14880 |
| 0.88 | 15120 |
| 0.89 | 15360 |
| 0.90 | 15600 |
| 0.91 | 15842 |
| 0.92 | 16080 |
| 0.93 | 16320 |
| 0.94 | 16560 |
| 0.95 | 16800 |
| 0.96 | 17040 |
| 0.97 | 17282 |
| 0.98 | 17520 |
| 0.99 | 17760 |
| 1.00 | 18000 |
Credit: [Analysis of query.time_of_day](https://gist.github.com/DoubleF3lix/a03afde0a979dfa41e8525ee92f12ca5)
</Spoiler>
## query.eye_target_x_rotation and query.eye_target_y_rotation
Not valid for player. not really sure what its good for.
## variable.short_arm_offset_right
Returns the offset factor for the player's rightarm bone compared to the default skin geometry. Slim-armed (3 pixel wide) skins will return `0.5` when equipped on the player. Normal (4 pixel wide) skins will return `0.0` when equipped on the player. Note: the player must go into 1st person perspective at least once for this variable to be initialized and usable elsewhere on the entity.
## variable.short_arm_offset_left
Identical behavior to `variable.short_arm_offset_right` except it references the player leftarm bone.
## query.movement_direction
Returns one of the 3 components from the normalized vector of the entity movement meaning the magnitude/modulus/length of the vector is between 0 and 1.
**Note**: As of writing the documentation, the value returned from any of the axis will change depending on the speed of the entity (If the entity is on the ground the value will be less than the value of the entity if it were in the air even if it is moving in the same direction).
To get the actual normalized velocity vector of the entity movement you will have to normalize the values. Here is the Molang setup:
```
variable.mag = math.sqrt( math.pow( query.movement_direction(0), 2 ) + math.pow( query.movement_direction(1), 2) + math.pow( query.movement_direction(2), 2));
variable.xNorm = query.movement_direction(0) / variable.mag;
variable.yNorm = query.movement_direction(1) / variable.mag;
variable.zNorm = query.movement_direction(2) / variable.mag;
```
For more information on normalized vectors you can play around with this <a href=https://www.desmos.com/calculator/hhoamwgve2>Desmos graph</a>
| Argument | Axis |
| -------- | ---- |
| 0 | X |
| 1 | Y |
| 2 | Z |
## query.block_neighbor_has_any_tag and query.relative_block_has_any_tag
Requires `Experimental Molang Features` to use. From the docs `Takes a relative position and one or more tag names, and returns either 0 or 1 based on if the block at that position has any of the tags provided`. This is useful for using connecting blocks or detecting entities.
`query.block_neighbor_has_any_tag` - Takes block position
`query.relative_block_has_any_tag` - Takes entity position
The syntax for it is `q.block_neighbor_has_any_tag(x,y,z,'tag_name')` and `q.relative_block_has_any_tag(x,y,z,'tag_name')`.
Example:
- `q.relative_block_has_any_tag(0,-1,0,'grass')` would try to detect a block with the grass tag one block under the entity.
- `q.block_neighbor_has_any_tag(0,-1,0,'grass')` would try to detect a block with the grass tag one block under the block.
To do multiple tags you would use `q.correct_query(0,-1,0,'grass', 'plant')` with `correct_query` being replaced by the right query.
Note that this can also detect custom tags and [vanilla tags](/blocks/block-tags)

40
docs/wiki/documentation/shared-constructs.md Normal file
View File

@@ -0,0 +1,40 @@
---
title: Shared Constructs
nav_order: 1
tags:
- Stable
- Last updated for Version 1.18.10
mentions:
- Ciosciaa
- ThomasOrs
---
A few JSON constructs are expressible in multiple locations in the add-ons system.
## Range Objects
Range objects define a spread between two numbers.
<CodeHeader>Range Object Example</CodeHeader>
```json
{
"min": 2,
"max": 4
}
```
When provided, a random value will be selected inclusively between the minimum and maximum. Rolls are not retained; a new random value will be rolled each instance the range object would be used. The maximum must not be less than the minimum, but they may be equal to affix rolls to a specific value.
## Fraction Objects
Fraction objects define a fraction using a numerator and denominator.
<CodeHeader>Fraction Object Example</CodeHeader>
```json
{
"numerator": 3,
"denominator": 5
}
```
The value used in place of the object will be the computed division, `numerator` ÷ `denominator`. Both the numerator and denominator must be at least `1`, and the denominator cannot be equal to the numerator.

2712
docs/wiki/documentation/sound-definitions.md Normal file
View File

File diff suppressed because it is too large Load Diff

72
docs/wiki/guide/addons.md Normal file
View File

@@ -0,0 +1,72 @@
---
title: Addons Explained
category: Guide
description: The basics of Addons
nav_order: 2
prefix: '2. '
mentions:
- SirLich
- Dreamedc2015
- sermah
- cda94581
- RedSmarty
- TheItsNameless
- MedicalJewel105
- ChibiMango
- profeplaysminecraft
- retr0cube
- SmokeyStack
---
## What are addons?
Addons allow us to modify the contents of our Minecraft Experience by _modifying_ or _removing_ existing content and _adding_ our own. Addons are very powerful and allow us to create custom entities, items, and blocks, as well as things like custom loot tables and crafting recipes. Your imagination is the limit!
Addons are primarily written in [json](/guide/understanding-json), which is a structured data-format. An addon is essentially a collection of json files, images, and sounds, which modify or add to the game in some way.
## What's the difference between a Behavior Pack & a Resource Pack?
Addons are split into two pack types: Resource Packs, and Behavior Packs. Both can function independently, but they are most commonly used together. When you have both a Resource Pack and Behavior Pack, this is referred to as an _addon_.
### Resource Pack
The Resource Pack, also known as the _client_, or RP, is responsible for the _visuals_ and _sounds_ in your addon. This includes things like:
- Textures
- Sounds
- Geometry
- Animations
- Particles
### Behavior Pack
The Behavior Pack, also known as the _server_, or BP, is responsible for the _logic_ of your addon. This can include things like:
- How your entity acts
- Crafting recipes
- Loot tables
- Custom functions
### Communication between packs
In most cases, you will have both a RP and a BP together. These packs can communicate with or will require each other for them to function properly, in the sense that assets defined in one can be accessed in the other. For example, when creating a custom entity, you need two files:
- An RP entity definition, which describes how your entity will _look_
- A BP entity definition, which describes how your entity will _act_
## What you have learned
:::tip
- Addons modify Minecraft content or add their own
- Addons are written in json
- An addon is split into the **Resource Pack** and the **Behavior Pack**: - Resource Packs contain Textures, Sounds, ... and control how the game looks - Behavior Packs contain entity-files, crafting recipes, ... and control the logic of your game
:::
## What to do now?
<BButton
link="/guide/software-preparation"
color=blue
>Check out software and preparation page!</BButton>

47
docs/wiki/guide/advancedmanifest.md Normal file
View File

@@ -0,0 +1,47 @@
---
title: Advanced Manifest
category: Extra
description: How to work with manifests - a more detailed guide [UNDER CONSTRUCTION]
nav_order: 4
prefix: 'd.'
mentions:
- MRBBATES1
- Luthorius
- SirLich
- smell-of-curry
- MedicalJewel105
- QuazChick
---
::: tip
This is an appendix page. You can start the guide from the beginning [here](/guide/index).
:::
This page is desgined to go into more detail about the manifest.json file, here we will cover what UUIDs are in more detail and how to add them. We will explain the use of dependencies, the different format versions, and how to include meta-data.
We will also go over the version differences between Behaviour packs, Resource packs, and Skin packs.
## UUIDs
UUID is an abbreviation for Universal Unique Identifier, there are 5 UUID versions plus one common unofficial version, A UUID is a 36 character string containing numbers, letters, and dashes.
Minecraft uses Version 4: Variant 1, which is completely random. This is what creates your pack's unique identity in Minecraft.
### How to Generate the correct UUID
You can use online sites such as [UUID Generator](https://www.uuidgenerator.net/version4/) and [UUID Tools](https://www.uuidtools.com/generate/v4) to generate the correct version required for Minecraft.
##
### UUID FAQ
- **Are UUIDs Case-sensitive?**
- _No, UUIDs are written in base 16 which uses numbers 0-9 and characters a-f. There is no distinction between upper and lowercase letters._
- **Can I use the same UUID for the header and the modules UUID?**
- _No, the UUID for the header and the module needs to be different._
:::warning
This page is under construction!
:::

283
docs/wiki/guide/blockbench.md Normal file
View File

@@ -0,0 +1,283 @@
---
title: 'Blockbench: Modeling, Texturing and Animating'
category: Guide
description: A first peek into Blockbench
prefix: '7. '
nav_order: 7
mentions:
- KaiFireborn
- SirLich
- Dreamedc2015
- SmokeyStack
- sermah
- cda94581
- TheItsNameless
- ThijsHankelMC
- MedicalJewel105
- ChibiMango
- smell-of-curry
---
Blockbench is a free software designed to make Minecraft modeling, texturing, and animating possible. It is available for mobile browsers, Windows 10, and macOS. Please install it at [blockbench.net](https://blockbench.net/).
Let's get started.
1. Open Blockbench.
2. Choose _File>New>Bedrock Model_. This is important because Minecraft Bedrock will not be able to read Java models.
3. A screen like this will have popped up.
![](/assets/images/guide/create_entity_project_menu.png)
- `"File name:"` is self-explanatory. My file will generate as "skele_yaklin.geo.json".
- `"Model Identifier:"` is the model identifier (namespace not required), a short name for this ID will be defined later.
- `"Box UV"` has to be checked on for automatic UV editing and unwrapping for texturing.
- `"Texture Height"` and `"Texture Width"` define the resolution of the model's textures.
4. Press confirm. You'll see a screen like this:
![](/assets/images/guide/create_entity_workspace.png)
- You can see many tools here: move, resize, rotate, etc.
- You can add bones and cubes in the menu on the right-bottom corner. Cubes can rotate on their own; the bones will carry everything in them along;
5. Now, you are ready to create your model! For more in-depth tutorials on modeling, please check out the videos by Everbloom Studio below.
<YouTubeEmbed id="XqzxL_-XjA0" />
<YouTubeEmbed id="j7ISUImhgpc" />
## Texturing
Now that you have your model in place let's start texturing!
1. On the left-bottom panel, click "Create Texture"
1. Write down your image file name under "Name:". Mine will export as `ghost.png`. Check "Template:" to make a template texture - it'll be easier to work with.
![](/assets/images/guide/create_entity_texture_1.png)
1. Check everything and change your resolution to the one you set in the very first step.
![](/assets/images/guide/create_entity_texture_2.png)
1. Go to "Paint" in the upper right corner and paint your texture.
## Animating
Once your model and texture are done, you can start animating. Go to "Animate" in the upper right corner.
You might want to adjust one of the toolbars by adding "Export Animations" and "Import Animations" like this:
![](/assets/images/guide/create_entity_animation_1.png)
1. Click "Add Animation" [the plus icon on the top right side] and name it `animation.{yourEntityName}.move`.
Create the first frame of your walking animation under 0 on the timeline by moving the legs.
![](/assets/images/guide/create_entity_animation_2.png)
1. Create the second frame under 0.5 on the timeline.
![](/assets/images/guide/create_entity_animation_3.png)
1. Finally, copy the first frame to the third frame by placing your timeline cursor on 1.0 and selecting the first frame, then ctrl+c, ctrl+v.
1. Right-click the animation and tick "Loop" for the animation to loop.
![](/assets/images/guide/create_entity_animation_4.png)
## Saving your work
Now that our model, texture, and walk animation are complete, you can save your work.
Go to _File > Save Model_ or _File > Export Bedrock Geometry_. Save the model in `RP/models/entity`, the texture in `RP/textures/entity/` and the animation in `RP/animations`. Congratulations! You've successfully created your first entity's visuals! You can see the file examples below.
_Meanwhile, why not upgrade the visuals of your own unique entities' or create another one?_
<Spoiler title="Show code">
<CodeHeader>RP/models/entity/ghost.geo.json</CodeHeader>
```json
{
"format_version": "1.12.0",
"minecraft:geometry": [
{
"description": {
"identifier": "geometry.ghost",
"texture_width": 64,
"texture_height": 64,
"visible_bounds_width": 3,
"visible_bounds_height": 3.5,
"visible_bounds_offset": [0, 1.25, 0]
},
"bones": [
{ "name": "root", "pivot": [0, 3, 0] },
{
"name": "body",
"parent": "root",
"pivot": [0, 4.625, 0],
"cubes": [
{
"origin": [-4, 3, -4],
"size": [8, 13, 8],
"uv": [0, 20]
}
]
},
{
"name": "leftArm",
"parent": "body",
"pivot": [4.6, 15.5, 0.5],
"cubes": [
{
"origin": [4.1, 7, -1],
"size": [3, 9, 3],
"uv": [32, 32]
}
]
},
{
"name": "rightArm",
"parent": "body",
"pivot": [-4.5, 15.5, 0.5],
"cubes": [
{
"origin": [-7.1, 7, -1],
"size": [3, 9, 3],
"uv": [32, 20]
}
]
},
{
"name": "head",
"parent": "body",
"pivot": [0, 16, 0],
"cubes": [
{
"origin": [-5, 16, -5],
"size": [10, 10, 10],
"uv": [0, 0]
}
]
}
]
}
]
}
```
<CodeHeader>RP/animations/ghost.a.animations.json</CodeHeader>
```json
{
"format_version": "1.8.0",
"animations": {
"animation.ghost.idle": {
"loop": true,
"animation_length": 3,
"bones": {
"body": {
"rotation": { "0.0": [10, 0, 0], "3.0": [10, 0, 0] },
"position": {
"0.0": [0, 0, 0],
"1.5": [0, 1, 0],
"3.0": [0, 0, 0]
}
},
"leftArm": {
"rotation": {
"0.0": [-10, 0, 0],
"1.5": [-5, 0, 0],
"3.0": [-10, 0, 0]
}
},
"rightArm": {
"rotation": {
"0.0": [-10, 0, 0],
"1.5": [-5, 0, 0],
"3.0": [-10, 0, 0]
}
},
"head": {
"rotation": {
"0.0": [-7.5, 0, 0],
"1.5": [-2.5, 0, 0],
"3.0": [-7.5, 0, 0]
}
}
}
},
"animation.ghost.attack": {
"animation_length": 0.75,
"bones": {
"body": {
"rotation": {
"0.0": [10, 0, 0],
"0.2917": [10, 15, 0],
"0.5": [22.5, -12.5, 0],
"0.75": [10, 0, 0]
},
"position": {
"0.0": [0, 0, 0],
"0.2917": [0, 0, 3],
"0.5": [0, 0, -3],
"0.75": [0, 0, 0]
}
},
"leftArm": {
"rotation": { "0.0": [-10, 0, 0], "0.75": [-10, 0, 0] }
},
"rightArm": {
"rotation": {
"0.0": [-10, 0, 0],
"0.2083": [-10, 0, 0],
"0.2917": [-10, 62.5, 117.5],
"0.5": [-80, -17.5, 22.5],
"0.75": [-10, 0, 0]
}
},
"head": {
"rotation": { "0.0": [-7.5, 0, 0], "0.75": [-7.5, 0, 0] }
}
}
},
"animation.ghost.move": {
"loop": true,
"animation_length": 1,
"bones": {
"body": {
"rotation": {
"0.0": [15, 0, 0],
"0.25": [15, -2.5, 0],
"0.5": [15, 0, 0],
"0.75": [15, 2.5, 0],
"1.0": [15, 0, 0]
},
"position": [0, 0, 0]
},
"leftArm": {
"rotation": {
"0.0": [15, 0, 0],
"0.5": [20, 0, 0],
"1.0": [15, 0, 0]
}
},
"rightArm": {
"rotation": {
"0.0": [15, 0, 0],
"0.5": [20, 0, 0],
"1.0": [15, 0, 0]
}
},
"head": {
"rotation": {
"0.0": [-12.5, 0, 0],
"0.5": [-15, 0, 0],
"1.0": [-12.5, 0, 0]
}
}
}
}
}
}
```
</Spoiler>
## What you have learned
<Checklist>
- [x] How to create an entity in Blockbench
- [x] How to use Blockbench to model, texture, and animate your entity
</Checklist>

1431
docs/wiki/guide/custom-entity.md Normal file
View File

File diff suppressed because it is too large Load Diff

322
docs/wiki/guide/custom-item.md Normal file
View File

@@ -0,0 +1,322 @@
---
title: 'Create a custom Item'
category: Guide
description: How to create your first custom Item
nav_order: 5
prefix: '5. '
mentions:
- KaiFireborn
- SirLich
- cda94581
- TheItsNameless
- MedicalJewel105
- ChibiMango
- TheDoctor15
- SmokeyStack
- unickorn
- Sprunkles317
- ThomasOrs
- davedavis
---
In Minecraft, we can create custom items, which can be dropped, traded, crafted, and otherwise used like a normal item. There is a lot of power in the system, including the ability to make food, fuel, and tools.
In this tutorial we are going to learn how to create a simple "ectoplasm" item, which we will later use as a loot-table drop for our ghost entity.
<br>
<img src="/assets/images/guide/custom_item/ectoplasm_view.png" width=150>
<br>
<br>
Conceptually, items are made up of two parts:
- The visuals (texture, name)
- The behaviors (how the item should behave)
First, we will learn how to create a new simple item & define its behaviors. In the next section we will assign a texture to this item, so you can see it in game.
:::warning
This guide requires experimental features toggled on.
:::
## Item Behavior
To make an item we will need a way to identify it and define how we want it to behave. To do this we will be making a file which tell Minecraft to apply certain behaviors to a specific item of our choice.
At the end of this section we will have fully defined the behavior of our item.
### Components
Different items behave differently; you can eat a porkchop, enchanted items glow & eggs can only stack to 16. These are all examples of how the item behaves.
We are able to define how our custom item will behave by using behavior components.
<Spoiler title="Example Components">
<CodeHeader>BP/items/example.json/components/</CodeHeader>
```json
"minecraft:food":
"minecraft:foil": true,
"minecraft:max_stack_size": 16
```
</Spoiler>
Components contain information which tells the game what our item should do. For example the component `"minecraft:foil"` determines whether the item should have an enchanted foil to it, so setting it to `true` will apply it.
All components have a `value` attached to it which we can edit to get the behaviour we want.
For our ectoplasm, we will set it to have a stack size of 16, similar to eggs. To do this we use the component `"minecraft:max_stack_size"` and set its value to `16`.
### Identifier
In order for the game to apply the correct components to the correct item, we need to be able to tell the game which item is ours. We do this by defining an identifier for our item.
An identifier is a name unique to this item. For a vanilla minecraft egg it's identifier is `minecraft:egg`. An identifier is made of two parts,
- The namespace (`minecraft`)
- The id (`egg`)
The namespace is unique to your addon and you will use it throughout the project. This is to reduce issues if someone adds two packs to your game which both add an ectoplasm item; the namespace reduces the chance of the identifier being the same.
The namespace that Minecraft use is `minecraft`. Your namespace should be unique to you, for example the authors initials or an abbreviation of the pack name. We will use the namespace `wiki` in our example; for more information on making a namespace check out our page [here](/concepts/namespaces).
The id is an informative shorthand name for your item. Here we will use `ectoplasm`.
Together our custom identifier becomes `wiki:ectoplasm`. Note that we use a colon, `:`, to spilt the namespace and id. When we want to reference our item we will use this identifier, for example using the `/give` command.
### Item File
Now that we have our components and identifier, we can now start defining our item. We define an item by creating an item definition file in our behavior pack. This is where all our information will go.
All item definitions go in `BP/items/`. The name of your file doesn't affect anything, but for ease of navigation it's recommend to name it after your id.
We will create a file `BP/items/ectoplasm.json`. Here is the the basic layout of the file:
<CodeHeader>BP/items/ectoplasm.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {...},
"components": {...}
}
}
```
Most files in your pack will have 2 top level definitions, `"format_version"` and `"minecraft:<file_type>"`.
The format version defines which version of the Addon system Minecraft will use to read this file. For our item, we will be using `1.16.100` to allow us to use the experimental features. For more information on format version you can check [here](/guide/format-version).
The second definitions defines what kind of file this is. In our case, as this is an item definition, it is `minecraft:item`. Under this is where we will put all our information. This will always contain a `description` key.
Let us look closer at the `"description"`:
<CodeHeader>ectoplasm.json/minecraft:item/</CodeHeader>
```json
"description": {
"identifier": "wiki:ectoplasm",
"category": "Items"
},
```
The description key contains the `identifier` and any other information required. The `identifier` allows the file to know which item to apply the components to.
The `category` key defines which tab of the creative inventory the item would show up in. There are four tabs to choose from: `"Nature"`, `"Equipment"`, `"Construction"` and `"Items"`. If this key is not included, then the item will not show in the creative inventory, but you can still get the item by using `/give`.
Now we can actually define the behavior of our item, under `components`. Here we simply place any components we want our item to have.
This will be our `"minecraft:max_stack_size"` component. For other components you can use, check out our more in depth guide on Items [here](/items/item-components).
<CodeHeader>ectoplasm.json/minecraft:item/</CodeHeader>
```json
"components": {
"minecraft:max_stack_size": 16
}
```
With that, we have now fully defined our item's behavior. This is what your file should currently look like.
<CodeHeader>BP/items/ectoplasm.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "wiki:ectoplasm",
"category": "Items"
},
"components": {
"minecraft:max_stack_size": 16
}
}
}
```
If you open a world with your addon, your item should be in the correct menu but invisible and have a strange name.
This is because we haven't defined the visuals yet. However, you should see that it does stack as expected. In the next section, we will define the items texture and assign it to our item.
## Item Visuals
Now that we have an item that works, we want to add a texture and name to it.
Textures are stored in the resource pack under `RP/textures` as images. In order for Minecraft to know which texture to use where, we need to assign a shortname to it, so we can access it.
### Texture
To start we need a texture for our item. For our ectoplasm, we will be using this image.
![ectoplasm.png](https://raw.githubusercontent.com/Bedrock-OSS/wiki-addon/86b0380310d3d5748a43a4be1f93d4c59668e4bf/guide/guide_RP/textures/items/ectoplasm.png)
<BButton link="https://raw.githubusercontent.com/Bedrock-OSS/wiki-addon/86b0380310d3d5748a43a4be1f93d4c59668e4bf/guide/guide_RP/textures/items/ectoplasm.png">Download texture here</BButton>
All item textures are stored in `RP/textures/items/`. From here, you can create any subdirectories you wish.
It's best to name your texture image files with the items' _id_, in our case it will be `ectoplasm.png`.
It is recommended to have your images in `.png` format and be of size `16x16`, though Minecraft will accept other formats such as `.jpg` or `.tga`.
Your folder layout should look like this:
<FolderView
:paths="[
'RP/textures/items/ectoplasm.png'
]"
/>
### Shortname
A shortname is essentially a name that is assigned to the folder path of the texture, so whenever we want to use a texture somewhere, we will use its shortname instead of its folder path.
All item shortnames are stored in one file called `item_texture.json` which is in `RP/textures`. This contains a list of shortnames and its assigned textures.
<CodeHeader>RP/textures/item_texture.json</CodeHeader>
```json
{
"resource_pack_name": "Ghostly Guide",
"texture_name": "atlas.items",
"texture_data": {...}
}
```
Here we have 3 top level definitions, `texture_data` is where we will define our shortnames, the other two define the type of file this is.
The `resource_pack_name` is simply our resource pack's name and `texture_name` is what kind of texture file this is. Since this is for _items_, this will always be set to `atlas.items`.
Under `texture_data` will our list of item shortname definitions. An example definition looks like this:
<CodeHeader>RP/textures/item_texture.json/texture_data</CodeHeader>
```json
"wiki.ectoplasm": {
"textures": "textures/items/ectoplasm"
}
```
Here `wiki.ectoplasm` is our shortname and under `textures` we have the path to our item. Notice that this is relative to the resource pack, and does not include the file extension. Your shortname should be short and unique. We recommend setting it as the namespace and id for the item we are assigning it to.
Now whenever we want to refer our image, we will use the shortname `wiki.ectoplasm`.
### Icon
To finally apply our texture to our item, we add the `minecraft:icon` component to our item definition and set its value to our shortname.
<CodeHeader>ectoplasm.json/minecraft:item/</CodeHeader>
```json
"components":{
"minecraft:max_stack_size": 16,
"minecraft:icon" : {
"texture": "wiki.ectoplasm"
}
}
```
Now your texture should appear on your item.
### Item Name
The last thing to add is a nice name to your item. Currently it will look like `item.wiki:ectoplasm`. This is the translation key for your item name, and it is used to allow for [localization](/concepts/text-and-translations). To set it, we just have to define it in our language files.
We already created these files when making our `RP` and `BP`, so we just need to add to them.
<CodeHeader>RP/texts/en_US.lang</CodeHeader>
```
item.wiki:ectoplasm=Ectoplasm
```
Now when you enter your world, your item should have a name.
## Overview
Now your first custom item, Ectoplasm, is complete! If everything has been done correctly, the item should now be obtainable through the `/give` command in-game, as well as appearing in your creative inventory.
Your folder structure should look like this:
<FolderView :paths="[
'RP/textures/item_texture.json',
'RP/textures/items/ectoplasm.png',
'RP/texts/en_US.lang',
'RP/texts/languages.json',
'RP/manifest.json',
'RP/pack_icon.png',
'BP/items/ectoplasm.json',
'BP/texts/en_US.lang',
'BP/texts/languages.json',
'BP/manifest.json',
'BP/pack_icon.png',
]"></FolderView>
<Spoiler title="Full ectoplasm.json">
<CodeHeader>BP/items/ectoplasm.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "wiki:ectoplasm",
"category": "Items"
},
"components": {
"minecraft:max_stack_size": 16,
"minecraft:icon": {
"texture": "wiki.ectoplasm"
}
}
}
}
```
</Spoiler>
<Spoiler title="Full item_texture.json">
<CodeHeader>RP/textures/item_texture.json</CodeHeader>
```json
{
"resource_pack_name": "Ghostly Guide",
"texture_name": "atlas.items",
"texture_data": {
"wiki.ectoplasm": {
"textures": "textures/items/ectoplasm"
}
}
}
```
</Spoiler>
If you're having some trouble, check the [Troubleshooting page](/items/troubleshooting-items). If that doesn't help, compare your results with the [example files](https://github.com/Bedrock-OSS/wiki-addon/tree/main/guide).
## Your progress so far
<Checklist>
- [x] Setup your pack
- [x] Create a custom item
- [x] How to format the behavior and resource files for an item
- [x] What components are and how to use them
- [x] How to set an items texture
- [ ] Create a custom entity
- [ ] Create the entity's loot, spawn rules, and a custom recipe
</Checklist>

33
docs/wiki/guide/download-packs.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: Download Example Packs
category: Extra
description: Appendix for downloading example Packs
prefix: 'b. '
nav_order: 2
show_toc: false
mentions:
- SirLich
- Joelant05
- Dreamedc2015
- sermah
- SmokeyStack
- MedicalJewel105
- Luthorius
- TheDoctor15
- TheItsNameless
---
::: tip
This is an appendix page. You can start the guide from the beginning [here](/guide/index).
:::
To get the most out of the guide, you should always attempt all guide-exercises yourself! However if you get very stuck, the example packs should give you some valuable reference material.
Download here:
<BButton
link="https://github.com/Bedrock-OSS/wiki-addon/releases/download/download/legacy_guide.mcaddon"
color=gray
>Download Add-On</BButton>
To install, simply unzip the behavior pack into the Minecraft folder: `com.mojang\development_behavior_packs` or `com.mojang\development_*_packs`, depending on which pack you downloaded.

110
docs/wiki/guide/format-version.md Normal file
View File

@@ -0,0 +1,110 @@
---
title: Format Versions
category: Extra
description: How to work with Format Versions
prefix: 'e. '
nav_order: 5
mentions:
- SirLich
- SmokeyStack
- ThomasOrs
- Xterionix
---
Format versions are an important part of Minecraft: Bedrock Edition's Addon System. They appear at the top of most files, formatted like this: `"format_version": "1.16.100"`. You can think of this as the "version number" of the file, and the number you select here is really important! The format version you select will define which syntax and features are available to you, in that particular file.
:::tip
Selecting the wrong format version is a common source of errors. When troubleshooting, people may ask you questions like 'what format version is your item'. Ensure that you know how to answer that question.
:::
## Why do format versions exist?
Format versions exist to *version* the Addon system, and allow Minecraft to introduce new features into the addon system, without breaking old Addons. For example, a `1.8.0` format version RP Entity file has very different syntax than a `1.10.0` format version RP Entity file. By using the 'format_version' key in the json *you* can decide which version you want to use.
By using format versions *per file*, Minecraft gives you a lot of control over how your addon will be interpreted by the game. It is completely possible and expected to mix different format versions in your addon.
## Experimental Format Versions
Format versions are also used for the purpose of versioning experimental features. Since Minecraft releases bedrock experiments directly into stable, some format versions will be 'locked' under experimental, unless you toggle the correct experiment.
A well known example is the item/blocks system, where `1.16.100` denotes experimental, and `1.10.0` denotes stable. If you want to make an item, it's important to select a format version early, as it will effect everything else you add to the files. If you are going with an experimental format version for your item/block you may want to go higher than `1.16.100` because some experimental features won't work properly in that format version, for example if you are making a custom spawn egg and you want it to be able to set the entity type of a monster spawner, then you need to the format version to `1.19.80` or higher.
## Format Version is not Game Version
It is really important to understand that format version is *per subsystem*, and is generally not equal to the base game version. This simply means that every type of file (item, rp entity, bp entity, recipe) will use a different versioning system.
For example: `"format_version": "1.8.0"` in an RP entity file means "use version `1.8.0` of the *item system*". It does *not* mean "use version `1.8.0` of the *addon system*".
For this reason, some file types will have very "old" format versions. Do not be tempted to replace this version with the latest game version, such as `1.17.0`.
## Format Version Fixing
Minecraft has a system that will "fix" your format version if you've written it wrong. This system isn't well understood, isn't enabled for all systems, and shouldn't be relied upon. But it's important to note that an incorrect format version will often "regress" downwards until it hits a valid format version. For example a `1.11.0` RP entity file will simply be interpreted as `1.10.0`, and cause no errors.
This system is useful, as it means you are less likely to generate a broken file, by selecting the wrong format version.
## Picking a Format Version
Generally speaking, there is a cool tricky to pick the correct format version, for any file type.
For example, imagine you are creating a Recipe file:
1) Install the [Vanilla Packs](/guide/download-packs).
2) Look at some recipe files, to judge which format version is most used, or the most recent
3) Use this format version in your file
This simple trick will help you select a valid format version for your file.
## Format Versions per Asset Type
This section will list the format versions used in the vanilla game, alongside how many times it appears.
- The '⭐' is the recommended *stable* version.
- The '🚀' is the recommended *experimental* version, where applicable.
### Resource Pack
| Resource Pack | Version | Count |
|----------------------|----------|-------|
| Entity | 1.10.0 ⭐ | 82 |
| Entity | 1.8.0 | 74 |
| Animation Controller | 1.10.0 ⭐ | 56 |
| Animation | 1.8.0 | 120 |
| Animation | 1.10.0 ⭐ | 6 |
| Attachables | 1.10.0 ⭐ | 29 |
| Attachables | 1.8.0 | 25 |
| Attachables | 1.10 | 1 |
| Models | 1.8.0 | 92 |
| Models | 1.12.0 | 19 |
| Models | 1.10.0 | 4 |
| Models | 1.16.0 | 7 |
| Particles | 1.10.0 ⭐ | 131 |
| Render Controllers | 1.10.0 ⭐ | 83 |
### Behavior Pack
| Category | Version | Count |
|-------------|------------|-------|
| Entities | 1.8.0 | 2 |
| Entities | 1.16.210 | 1 |
| Entities | 1.13.0 | 7 |
| Entities | 1.16.0 ⭐ | 58 |
| Entities | 1.16.100 | 3 |
| Entities | 1.12.0 | 21 |
| Entities | 1.17.20 | 7 |
| Entities | 1.17.10 | 4 |
| Entities | 1.10.0 | 1 |
| Entities | 1.14.0 | 1 |
| Items | 1.10 ⭐ | 44 |
| Items | 1.16.0 | 1 |
| Items | 1.16 | 1 |
| Items | 1.14 | 1 |
| Items | 1.16.100 🚀 | 0 |
| Items | 1.19.80 | 0 |
| Items | 1.20.40 | 0 |
| Recipes | 1.12 | 991 |
| Recipes | 1.16 ⭐ | 194 |
| Recipes | 1.14 | 2 |
| Spawn Rules | 1.8.0 ⭐ | 48 |
| Spawn Rules | 1.17.0 | 1 |
| Spawn Rules | 1.11.0 | 1 |

13
docs/wiki/guide/index.md Normal file
View File

@@ -0,0 +1,13 @@
---
title: Beginners Guide
nav_order: 1
categories:
- title: Guide
color: green
- title: Extra
color: blue
---
Welcome to the Bedrock Beginners Guide!
<BButton color="blue" link="introduction">Get Started!</BButton>

60
docs/wiki/guide/introduction.md Normal file
View File

@@ -0,0 +1,60 @@
---
title: Introduction
category: Guide
description: Introduction to our "Getting Started" Guide
tags:
- guide
nav_order: 1
prefix: '1. '
mentions:
- KaiFireborn
- SirLich
- BlueFrog130
- sermah
- SmokeyStack
- TheItsNameless
- MedicalJewel105
- smell-of-curry
- Hatchibombotar
- retr0cube
---
## What are Addons?
An "Addon" is the Minecraft Bedrock Edition (_Windows 10, iOS, Android, Consoles_) equivalent to Java mods. However, in contrast to Java, the Bedrock Edition API is officially maintained by Mojang instead of the community.
In general, you can think of _mods_ as _modifying_ the game, and _addons_ as _adding onto_ the game, following the development opportunities provided by Microsoft.
## What is this guide?
This guide is a beginner tutorial, intended to walk you through the first stages of addon-creation. You will create your very own fully-functional Ghost entity, as well as an Ectoplasm item, and some other associated files.
By the end of this guide, you will have created an entire addon all by yourself, which you can play with and modify!
In this guide you will find boxes like these:
:::tip
Some very helpful information!
:::
:::warning
Attention! Watch out for these common mistakes.
:::
Watch out for these boxes! They contain very important information that could help you with problems.
## Is the guide up to date?
This guide is written for the most recent _stable_ release of Minecraft Bedrock Edition. Many things won't work in previous versions, and some will be changed in later ones. We will keep the guide as up-to-date as possible, so no need to worry.
## Appendix Pages
Alongside the step-by-step guide, we have a few other files here, which may be interesting to you:
- [Understanding JSON](/guide/understanding-json)
- [Downloading Example Packs](/guide/download-packs)
- [Troubleshooting](/guide/troubleshooting)
## What to do after finishing the Guide
At the end of the guide section, your first addon will be done! To further expand your knowledge, consider doing these:
- Start your project!
- To dive into the other aspects of adding onto MCBE (Minecraft Bedrock Edition), you can use the different sections' sub guides listed in the Appendix. This includes but is not limited just to custom Blocks, Biomes, advanced Items, Animation Controllers, and even JS scripts. Some sections provide more technical in-depth tutorials and documents for each relevant topic.

179
docs/wiki/guide/loot-table.md Normal file
View File

@@ -0,0 +1,179 @@
---
title: 'Adding a Loot Table, a Spawn rule and a crafting recipe'
category: Guide
description: How to add your first Loot Table, Spawn Rule and Crafting Recipe
nav_order: 8
prefix: '8. '
mentions:
- KaiFireborn
- SirLich
- sermah
- cda94581
- Ultr4Anubis
- TheItsNameless
- Ciosciaa
- MedicalJewel105
- ChibiMango
- FrankyRay
---
Next, we'll enhance the custom Ghost entity by adding some more basic mechanics to it:
## Loot tables
First, we'll make the ghost drop Ectoplasm upon death: create the following file:
<CodeHeader>BP/loot_tables/entities/ghost.json</CodeHeader>
```json
{
"pools": [
{
"rolls": 1,
"entries": [
{
"type": "item",
"name": "wiki:ectoplasm",
"weight": 1,
"functions": [
{
"function": "set_count",
"count": {
"min": 1,
"max": 3
}
}
]
}
]
}
]
}
```
- Loot Tables consist of `"pools"`. Each pool defines a different loot. A pool consists of 3 parts, `"rolls"`, `"entries"` and `"conditions"`. The `"conditions"` are optional and won't be covered in this guide. To learn more about conditions, look at [Loot Tables](/loot/loot-tables).
- The `"rolls"` section defines how many times a random entry will be chosen from the following `"entries"`object.
- The `"entries"` part defines the items, from which the loot table can choose. Each roll a new item will be chosen.
- `"type"` defines what will be chosen. You can set it to `"item"` or `"loot_table"` to either chose an item or an different loot table.
- `"name"` will be set to an item identifier with its namespace. It defines which item will be selected.
- `"weight"` is optional and defines how likely it is, that this item will be selected. If there is more than one item in the `"entries"` section, the `"weight"` attribute can be used to make the probability of one item more or less likely. If it isn't set, it defaults to 1.
- `"functions"` provide a powerful way of customizing the item that will be returned. They can add enchantments to an item, setting an items' name or simply setting the number of items that will be dropped. To define the number of items, we use `"set_count"`. It takes the `"count"` attribute, which sets the maximum and minimum amount of items that will be dropped.
For more information on loot tables, see our extended guide: [Loot Tables](/loot/loot-tables)!
## Spawn rules
Next, we'll make the ghost spawn in deserts at night:
<CodeHeader>BP/spawn_rules/ghost.json</CodeHeader>
```json
{
"format_version": "1.8.0",
"minecraft:spawn_rules": {
"description": {
"identifier": "wiki:ghost",
"population_control": "monster"
},
"conditions": [
{
"minecraft:spawns_on_surface": {},
"minecraft:brightness_filter": {
"min": 0,
"max": 7,
"adjust_for_weather": true
},
"minecraft:difficulty_filter": {
"min": "easy",
"max": "hard"
},
"minecraft:weight": {
"default": 80
},
"minecraft:herd": {
"min_size": 1,
"max_size": 3
},
"minecraft:biome_filter": {
"test": "has_biome_tag",
"operator": "==",
"value": "desert"
}
}
]
}
}
```
- You already know what `"format_version"`does.
- Inside the `"minecraft:spawn_rules"` part we define our spawn rules.
- The `"description"` defines the basic properties of the file. The `"identifier"` is used to define on which entity this spawn rule applies on. `"population_control"` is used to limit the amount of entities that will be spawned. Once the pool that is defined inside of `"population_control"` is full, no more entities will be spawned.
- With `"conditions"` we can define rules that limit the spawning of this entity to special cases. We will shortly describe each condition used here, but you can learn more conditions and how to use them [here](/entities/vanilla-usage-spawn-rules).
- `"spawns_on_surface"` allows the mob to only spawn on surfaces.
- `"minecraft:brightness_filter"` limits the spawning to areas with a lighting level thats between the defined values. If `"adjust_for_weather"` is `true`, the light level decrease during rain and storms will be ignored.
- `"minecraft:difficulty_filter"` defines the difficulty level needed to spawn the entity.
- `"weight"` defines how often this entity will spawn. The higher this value, the more often the mob will spawn.
- `"minecraft:herd"`defines how many entities will be spawned at once.
- With `"minecraft:biome_filter"` we define the biomes in which the entity is able to spawn.
To learn more about spawn rules, take a look on our guide on [Vanilla spawn rules](/entities/vanilla-usage-spawn-rules).
## Crafting recipes
And finally, as an introduction to recipes, we'll make the Ectoplasm craftable into Slime Blocks:
<CodeHeader>BP/recipes/ectoplasm_slime_blocks.json</CodeHeader>
```json
{
"format_version": "1.12.0",
"minecraft:recipe_shaped": {
"description": {
"identifier": "wiki:ectoplasm_slime_block"
},
"tags": ["crafting_table"],
"pattern": ["###", "###", "###"],
"key": {
"#": {
"item": "wiki:ectoplasm"
}
},
"result": {
"item": "minecraft:slime"
}
}
}
```
- `"format_version"` is already known.
- With `"recipe_shaped"` we define, that each ingredient has a set place in the crafting grid. There are some other types that can be used, you can find more information [here](/loot/recipes).
- Inside `"description"` we define the `"identifier"` of this recipe, which is the name of the recipe.
- `"tags"` is a list of benches (crafting table, furnace, etc) that are able to use this recipe. After version b1.16.100 it was possible to use custom benches, created by an addon.
- `"pattern"` defines the arrangement of the items inside the crafting grid. Each `#` represents the item that is set under `"key"`. In this case, the whole 3x3 grid has to be filled with `"wiki:ectoplasm"`, our own item. It is possible to define more items, just add an entry to `"key"` and set the key to a character, that you can use inside `"pattern"`.
- `"result"` contains an `"item"`, which is set to the item that will be the output of this recipe.
For more information on this topic, visit our page about [recipes](/loot/recipes)!
## What you have learned
:::tip What you have learned:
- How to create a loot table and define which items a mob is able to drop
- How to set the rules for a mob to spawn
- How to create new crafting recipes
:::
## Your progress so far
**What you've done:**
<Checklist>
- [x] Setup your pack
- [x] Create a custom item
- [x] Create a custom entity
- [x] Create the entity's loot, spawn rules, and a custom recipe
</Checklist>
Congratulations! you have finished the Guide and created your first Add-on. 🎉

261
docs/wiki/guide/project-setup-android.md Normal file
View File

@@ -0,0 +1,261 @@
---
title: Project Setup Android
category: Guide
description: How to setup your project on Android
mentions:
- Etanarvazac
- MedicalJewel105
- TheItsNameless
- ThomasOrs
hidden: true
---
## Tools
It is not easy to find good apps to make add-ons for android platform, but we tried our best and collected Google Play apps for you.
For development on Android, you'll need a combination of 3 applications.
1. A file manager that can create ZIP archives if your device is running Android 12 or newer.
2. A code editor (any text editor will work, but only code editors will show syntax highlights).
3. An image editor (no device comes with a editor that can go down to the pixels).
### File Managers
These file managers are known to have ZIP archiving and view-only access to the `Android/data` folder:
1. [**X-Plore**](https://play.google.com/store/apps/details?id=com.lonelycatgames.Xplore) - a powerful file manager with dual-pane tree view, a built-in text editor (not code), several file compression formats (ZIP, 7zip, RAR, etc.), and more. On rooted devices, X-Plore has edit access to `Android/data` and root directories.
2. [**Total Commander**](https://play.google.com/store/apps/details?id=com.ghisler.android.TotalCommander) - not as powerful out of the box compared to X-Plore, but contains some of the same features including dual pane, ZIP and RAR archives, and view-only access to `Android/data`. Total Commander has list view instead of tree and many other features that require plugins (apps from Google Play) to use.
### Code Editors
1. **Acode:** [Free version](https://play.google.com/store/apps/details?id=com.foxdebug.acodefree) comes with ads that can be toggled off without paying. Supports GitHub integration using a Personal Access Token, FTP/SFTP, syntax highlighting for over 100+ languages including JSON, tab-view for multi-file editing, dozens of themes, and more. This app is open source and does have a [paid version](https://play.google.com/store/apps/details?id=com.foxdebug.acode) that allows a much deeper theme customization.
:::info
Acode is the only powerful code editor actively being developed on Android at this time. Other editors are very limited or have been abandoned long enough to vanish from the Google Play store. If you know of a code application, you can contribute to this guide.
:::
### Image Editors
1. [**Pocket Paint**](https://play.google.com/store/apps/details?id=org.catrobat.paintroid) - lightweight editor with the bare minimum features needed for any add-on creation. This app is easy to use and allows importing other images over others. Saves in JPG (compressed), PNG (lossless, with transparency), and ORA (multi-layer images). This app is open source.
2. [**Pixly**](https://play.google.com/store/apps/details?id=com.meltinglogic.pixly&hl=en) - very lightweight, no ads or in app purchases. Plentiful tools and customizable brushes, ability to save palettes internally or externally.
3. [**Pixel Art editor**](https://play.google.com/store/apps/details?id=net.spc.app.pixelarteditor&hl=en) - a simple lightweight app. Would be the best if you need just to draw some texture-placeholder.
## Your Workspace
:::tip
In this version of the guide, "BP" refers to your behaviour pack folder and "RP" refers to your resource pack folder in your workspace. For locations in files or directories, `../<current location>` indicates "From last location" followed by the added space (e.g.: `/one/two/three/file.txt` would be shortened to `../three/file.txt`)
If your device is rooted, you can follow the main project setup using the `/Android/data/com.mojang.minecraftpe/files/games/com.mojang` development behaviour and resource pack folders directly. Otherwise, follow the steps below.
:::
Before we begin, you need a workspace. Using your file manager, navigate to your Internal Storage (In most cases, it's `/`. In others, the full path (e.g.: `/storage/emulated/0/`) is displayed. Both are acceptable.) and create a folder that will contain your packs. For this example, our full directory is `/Minecraft Packs/MyFirstAddon`. From there, you'll need one folder for both your behaviour and resource packs (e.g.: `../MyFirstAddon/addonBP` and `../MyFirstAddon/addonRP`).
Now that you have the workplace setup, code editors should have a way for you to open a folder as a workplace. In this guide, we'll be walking through Acode.
1. Open Acode.
2. Tap the file browser button (3 bars in the top-left), followed by "Open folder"
3. Tap "Add a storage", followed by "select folder"
4. This should have opened your device's file browser. Navigate to the _main_ folder for your projects (for us, `/Minecraft Packs`) then tap "Use this folder". If your device asked you to allow Acode access, tap "Allow".
5. You should be back in Acode now. Tap "OK" and your folder should now be in the list. Tap on it and then "Select Folder" on the bottom of the screen.
6. Now when you open the file browser (3 bars in top-left), you should see your folder in the list. You now have quick access to your addon's behaviour and resource pack folders. The file browser uses tree view to display your active workspace.
:::tip
You can create new files and folders inside your packs from the file browser by tapping and holding on the folder you want to create the item in.
:::
## BP & RP Manifests
:::warning
From here on out, all files and folders have very specific names unless otherwise noted. Wrongly named files and/or folders are a common reason of an error. Please ensure you're checking your work carefully in accordance to the examples provided. If a file or folder mentioned has not yet been created, please create it in it's appropriate directory.
When creating a new file in a file manager or some text or code applications, the `.txt` extension is added automatically to the end of the file name. To ensure our files work as intended, be sure to remove `.txt`. Like names, the wrong file extension is also a common reason of an error. If you're using Acode, you'll notice `untitled.txt` is completely highlighted instead of just `untitled`. This is a common practice for naming programming language files.
:::
The manifest file is the file Minecraft uses to identify your packs. Every pack has one (and only one) manifest. A folder with a correctly formatted manifest will show up in Minecraft. Before we begin adding content, we will ensure our "minimal" pack is visible. Manifests are written in the `JSON` programming language. If you're unfamiliar with JSON, you can learn more about it [here](/guide/understanding-json).
Create a new text file in your addon's behaviour pack folder called `manifest.json`. To begin, copy and paste the following code into the `manifest.json` file. A full breakdown of the manifest file is provided after creating these files.
<codeHeader>BP/manifest.json</codeHeader>
```json
{
"format_version": 2,
"header": {
"name": "pack.name",
"description": "pack.description",
"uuid": "...",
"version": [0, 0, 1],
"min_engine_version": [1, 16, 0]
},
"modules": [
{
"type": "data",
"uuid": "...",
"version": [0, 0, 1]
}
]
}
```
Now create another `manifest.json` file in your addon's resource pack folder. Again, copy and paste the following code inside the new file.
<codeHeader>RP/manifest.json</codeHeader>
```json
{
"format_version": 2,
"header" {
"name": "pack.name",
"description": "pack.description",
"uuid": "...",
"version": [0, 0, 1],
"min_engine_version": [1, 16, 0]
},
"modules": [
{
"type": "resources",
"uuid": "...",
"version": [0, 0, 1]
}
]
}
```
## Manifest Breakdown
- `format_version` defines the version the syntax your manifest is written in. Version 2 is the most recent stable version. Always use this version.
- `name` is name of your pack. We will be defining the this in "code form" later so they can easily be translated into other languages, should you create a pack with multiple languages.
- `description` is a short description about your pack that will show up under the `name` in-game. This will also be defined later in "code form".
- `uuid` is required to help identify your pack from other packs and will have a breakdown of it's own below. Once explained, you'll need to replace all of the `...` with them.
- `version` is literally the version of your addon. Upon completing your addon, you can always change this to `[1, 0, 0]`. However, it'll be easier to use the hotfix spot while making your changes on mobile.
- `min_engine_version` tells Minecraft what the minimum version it needs to be in order for your pack to work. For example, if your pack has a crafting recipe that involves concrete, your pack can't run on Minecraft 1.5 because concrete doesn't exist in that version.
- Under `modules`, you have the `type` field. This tells Minecraft what your pack is. So `data` in your BP tells the game that pack is a behaviour pack and `resources` in your RP tells the game that pack is a resource pack.
## UUID Breakdown
A UUID, or **U**niversally **U**nique **ID**entifier, both identifies your pack for other programs (Minecraft, for example) and separates your pack from someone else's pack for the program it's for. A version 4 UUID (UUID-4) is usually in the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` and made of a random string of letters and numbers. For example: `5c830391-0937-44d6-9774-406de66b6984`.
You should **NEVER** use the same UUID twice! Use the [Online UUID Generator Tool](https://www.uuidgenerator.net/version4) to generate the UUID's needed for your manifest files. Every manifest file uses two different UUID's. So to ensure your packs will work correctly, get 4 different UUID's to replace all of the `...` in both manifests. When finished, each UUID entry should look similar like this: `"uuid": "5c830391-0937-44d6-9774-406de66b6984`
## Pack Icon
Notice how other packs have a icon? It's a image file which can quickly identify how your addon will appear in-game. Got a low-resolution square image as a PNG? You can use it! Otherwise, you can use this example icon.
<WikiImage src="/assets/images/guide/project-setup/pack_icon.png" alt="Pack Icon" pixelated/>
<BButton
link="/assets/images/guide/project-setup/pack_icon.png" download
color=default
>Download Image</BButton>
You must place a copy of your desired image in both the behaviour and resource packs. In order for the image to be read correctly, the name must be `pack_icon.png`.
## Language Files
Remember when we said we'll define the pack name and description in code form earlier? Now is that time as it's the last thing we need to do to setup your addon. You will need to create 4 new files and 2 new folders (2 files and 1 folder for each pack). You can You can learn more about how Minecraft handles localization [here](/concepts/text-and-translations). You can also format your definitions using the `§` symbol. You can view a list of colors and formats [here](https://htmlcolorcodes.com/minecraft-color-codes/). If you use any formatting, make sure you `§r`eset when changing formats: `§kl My pack l` will render "My pack" unreadable whereas `§kl §rMy pack §kl` can be read properly.
<codeHeader>BP/texts/en_US.lang</codeHeader>
```
pack.name=§2My §lFIRST §r§2Addon's Behaviour Pack!
pack.description=This addon is made by a Wiki Contributor!
```
<codeHeader>BP/texts/languages.json</codeHeader>
```json
["en_US"]
```
<codeHeader>RP/texts/en_US.lang</codeHeader>
```
pack.name=§2My §lFIRST §r§2Addon's Resource Pack!
pack.description=This addon is made by a Wiki Contributor!
```
<codeHeader>RP/texts/languages.json</codeHeader>
```json
["en_US"]
```
## Importing Your Addon
Now that your addon has all of the required content, we need to import it to Minecraft. To do this, we need to create a file with the extension `.mcaddon`.
1. Open your preferred file manager and navigate to the folder containing your behaviour and resource packs.
2. Using multi-select, select both packs and create a ZIP file.
3. When asked for the name of the file, ensure that `.zip` is changed to `.mcaddon`.
![](/assets/images/guide/project-setup-android/zip-addon.png)
4. When your file manager finishes, it should be a `MCADDON` file with Minecraft as it's icon. Tapping on this file should launch Minecraft.
If done correctly, Minecraft will display a banner for both packs. First is `Importing...`. After should be `Successfully imported "<your pack name>"`. You can also go to `Settings > Storage` if you don't see the import messages to verify your packs were imported. If you do not see either pack, check out our [troubleshooting guide](/guide/troubleshooting).
## Turn on Content Log
:::warning
Content log is the most useful tool you have for debugging your addons. Please do not skip this step.
:::
![](/assets/images/guide/content_log.png)
Content Log is an extremely important debugging tool, which you should always have on.
Turn on both content log settings in `settings > creator`. This will show you any errors in your add-on when you enter a world with it applied. You can also open the content log GUI in-game by pressing `ctrl+h`. Learn more about the content log [here](/guide/troubleshooting).
## Creating your testing world
Now we create a world to test your new add-on!
1. Click "**Create new world**";
2. Ensure that the following settings are set.
![](/assets/images/guide/project-setup/settings_1.png)
![](/assets/images/guide/project-setup/settings_2.png)
3. Now activate your behavior pack, and your resource pack. You can do this by selecting the packs, and clicking 'apply'.
4. Now click '**Create**'!
## Final Notes
**Here is how your project should look, after completing this page:**
Remember that in future, we will represent `com.mojang/development_behavior_packs/guide_RP/` as `RP`, and `com.mojang/development_behavior_packs/guide_BP/` as `BP`.
<FolderView :paths="[
'com.mojang/development_resource_packs/guide_RP/manifest.json',
'com.mojang/development_resource_packs/guide_RP/pack_icon.png',
'com.mojang/development_resource_packs/guide_RP/texts/en_US.lang',
'com.mojang/development_resource_packs/guide_RP/texts/languages.json',
'com.mojang/development_behavior_packs/guide_BP/manifest.json',
'com.mojang/development_behavior_packs/guide_BP/pack_icon.png',
'com.mojang/development_behavior_packs/guide_BP/texts/en_US.lang',
'com.mojang/development_behavior_packs/guide_BP/texts/languages.json',
]"></FolderView>
## What you have learned
:::tip What you have learned:
- What and where your `com.mojang` folder is and what it contains
- How to setup your mobile workspace
- What a `manifest.json` file is
- What are UUID's and how to use them
- How to create icons for your addons
- What a `.lang` file is
:::
## Your progress so far
<Checklist>
- [x] Setup your pack
- [ ] Create a custom item
- [ ] Create a custom entity
- [ ] Create a custom block
</Checklist>

300
docs/wiki/guide/project-setup.md Normal file
View File

@@ -0,0 +1,300 @@
---
title: Project Setup
category: Guide
description: How to setup your project
nav_order: 4
prefix: '4. '
mentions:
- SirLich
- sovledDev
- Joelant05
- Dreamedc2015
- BlueFrog130
- sermah
- cda94581
- MedicalJewel105
- TheItsNameless
- ThijsHankelMC
- TheHyperWhale
- stirante
- ChibiMango
- Etanarvazac
- retr0cube
- ThomasOrs
- lescx
---
## The com.mojang folder
The `com.mojang` folder is a special folder where Minecraft stores data (Addons, Worlds, Player info...). Minecraft understands this location, and all files we access or create will be placed somewhere in this folder!
You should create a shortcut to the `com.mojang` folder on your Desktop or on your mobile device, so you can easily access it at any time. The exact location of the `com.mojang` folder will depend on your device OS.
### Windows
_Tip: You can type %appdata% into the searchbar to jump directly into the 'C:\Users\USERNAME\AppData\' folder._
`C:\Users\USERNAME\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang`
### Android
Android 11 or older: `Phone > games > com.mojang`
Android 12 and newer: `Phone > Android > data > com.mojang.minecraftpe > files > games > com.mojang`
### ChromeOS
Before you can see the `com.mojang` in your files, make sure to change the `File Storage Location` to `External` in your Minecraft Settings:
- Go to `Minecraft Settings`.
- Navigate to `Settings > General > Storage`.
- Change the `File Storage Location` to `External`.
After that you can access the `com.mojang` folder in your Android Subsystem:
`My Files > Play Files > Android > data > com.mojang.minecraftpe > files > games > com.mojang`
### iOS
`My iDevice > Minecraft > games > com.mojang`
### Development Packs
We will develop our addon in `development_behavior_packs` and `development_resource_packs`. When you make changes within these folders, you can _exit and re-enter a world with the packs applied_, to automatically reload the content. This allows you to quickly test your addon without reloading Minecraft.
`resource_packs` and `behavior_packs` on the other hand contain stable addons, including those imported via `.mcpack`. We can ignore these folders for now.
## Your Workspace
:::tip
Project setup is different for android and other platforms. Consider looking into our guide for android platforms.
:::
<BButton
link="./project-setup-android"
color=blue
>Android guide</BButton>
:::tip
In this guide, BP refers to the folder you created in `development_behavior_packs` ("the behavior pack"), and RP refers to the folder you created in `development_resource_packs` ("the resource pack")
:::
First of all, you will need to create the proper folders in suitable locations and set up your workspace.
_The remainder of this guide assumes you are using VSCode. You may also follow along with other editors._
Let's create your first add-on workspace in Visual Studio Code now.
1. Open VSCode (_Visual Studio Code, the code editor_)
2. Create a folder named "`your_pack_name_RP`" in `development_resource_packs`. **I'll refer to this folder as `RP`**
3. Create a folder "`your_pack_name_BP`" in `development_behavior_packs`. **I'll refer to this folder as `BP`**.
4. Go to `File > Add folder to workspace...` and choose `BP`. Do the same with `RP`.
5. Press `File > Save Workspace as...` to save the workspace file to your Desktop. Whenever you're working on your addon, all you have to do is open the workspace by double-clicking, and you will get quick access to both BP and RP folders.
## BP Manifest
:::tip
In this guide, you will often be instructed to create files with specific names, placed in specific folders. If the folder doesn't exist yet, please create it!
:::
:::warning
Wrongly named files/folders is a common source of errors. Please check your work carefully against the examples.
:::
The manifest is a file that identifies your pack to Minecraft. Every pack has one manifest. A folder with a correctly formatted manifest will show up in Minecraft, and we consider this the "minimal" pack before we can add additional content.
Manifest files are written in `json`. If this isn't familiar to you, you can learn more about json [here](/understanding-json).
First, create a new file in your BP folder by right-clicking on the folder and selecting `New File`. Call the file `manifest.json`. To begin, you can copy paste the following code into the file.
<CodeHeader>BP/manifest.json</CodeHeader>
```json
{
"format_version": 2,
"header": {
"name": "pack.name",
"description": "pack.description",
"uuid": "...",
"version": [1, 0, 0],
"min_engine_version": [1, 16, 0]
},
"modules": [
{
"type": "data",
"uuid": "...",
"version": [1, 0, 0]
}
]
}
```
### Manifest Explained
- "`format_version`" defines what version of manifest syntax you are using. Version 2 is the most recent stable version; use it.
- "`name`" is the name of your behavior pack. "`description`" will show up under it in-game. We are defining these files in "code form" so we can translate them later into other languages. For more information about localization, look [here](/concepts/text-and-translations).
- The "`UUID`" field is **essential**, and will be discussed in more detail below.
- "`version`" defines the version of your add-on. When you import an add-on with a newer version on a device with an older version installed, the more recent version will overwrite the older one. You don't need to change the version if you have the add-on in `development_*_packs` folders and only use them on private worlds.
- "`min_engine_version`" defines the minimum Minecraft client version that'll be able to read your add-on.
- In "`modules`", the "`type`" is defined to be "`data`". This makes your pack a _Behavior Pack_.
### UUID Explained
A UUID (_Universally Unique Identifier_) identifies your pack for other programs (in this case, Minecraft) to read. It looks something like this: `5c830391-0937-44d6-9774-406de66b6984`
**NEVER USE THE SAME UUID TWICE.** You can generate your own UUIDs [here](https://www.uuidgenerator.net/version4) or, if you use VSCode, you can install [this](https://marketplace.visualstudio.com/items?itemName=netcorext.uuid-generator) extension. Many other tools like _bridge._ generate UUIDS automatically. Every manifest file uses two different UUIDs.
To ensure that your add-on will work correctly you should generate two new UUID's which you will paste into the BP `manifest.json` file, at each `"..."`. When you are finished, it should look something like this:
`"uuid": "5c830391-0937-44d6-9774-406de66b6984"`
## RP Manifest
The next step is to create the `manifest.json` for the RP. The format for a resource-pack manifest is nearly identical to a BP manifests except that the `type` is `resources`, which marks the pack as a _Resource Pack_.
Copy the following code into your newly created `RP/manifest.json` and insert your own UUIDs.
<CodeHeader>RP/manifest.json</CodeHeader>
```json
{
"format_version": 2,
"header": {
"name": "pack.name",
"description": "pack.description",
"uuid": "...",
"version": [1, 0, 0],
"min_engine_version": [1, 16, 0]
},
"modules": [
{
"type": "resources",
"uuid": "...",
"version": [1, 0, 0]
}
]
}
```
## Pack Icon
The pack icon is an image file which identifies how your addon will look in-game. If you have a low-resolution square image, you can use it. Otherwise, download and use this example icon:
<WikiImage src="/assets/images/guide/project-setup/pack_icon.png" alt="Pack Icon" pixelated/>
<BButton
link="/assets/images/guide/project-setup/pack_icon.png" download
color=default
>Download Image</BButton>
You should place a copy of your desired image into both the RP and the BP. The image needs to be named `pack_icon.png`
## Language Files
The last thing to do is setup language support for your addon. You will need to create a language file for both the RP and the BP. You can learn more about how Minecraft handles localization [here](/concepts/text-and-translations).
<CodeHeader>RP/texts/en_US.lang</CodeHeader>
```json
pack.name=Wiki Resource Pack
pack.description=A Ghostly Guide
```
<CodeHeader>BP/texts/en_US.lang</CodeHeader>
```json
pack.name=Wiki Behavior Pack
pack.description=A Ghostly Guide
```
<CodeHeader>RP/texts/languages.json</CodeHeader>
```json
["en_US"]
```
<CodeHeader>BP/texts/languages.json</CodeHeader>
```json
["en_US"]
```
## Checking your Work
If you have done everything correctly, your packs should show up in Minecraft now! If you don't see your pack, you should follow the [troubleshooting guide.](/troubleshooting)
![](/assets/images/guide/project-setup/active_pack.png)
## Turn on Content Log
:::warning
Content log is the most useful tool you have for debugging your addons. Please do not skip this step.
:::
![](/assets/images/guide/content_log.png)
Content Log is an extremely important debugging tool, which you should always have on.
Turn on both content log settings in `settings > creator`. This will show you any errors in your add-on when you enter a world with it applied. You can open the content log GUI in-game by pressing `ctrl+h` or by pressing `Content Log History` in the creator settings panel. Learn more about the content log [here](/guide/troubleshooting).
## Creating your testing world
Now we create a world to test your new add-on!
1. Click "**Create new world**";
2. Ensure that the following settings are set.
![](/assets/images/guide/project-setup/settings_1.png)
![](/assets/images/guide/project-setup/settings_2.png)
3. Now activate your behavior pack, and your resource pack. You can do this by selecting the packs, and clicking 'apply'.
4. Now click '**Create**'!
---
## Your progress so far
**Here is how your project should look, after completing this page:**
Remember that in future, we will represent `com.mojang/development_behavior_packs/guide_RP/` as `RP`, and `com.mojang/development_behavior_packs/guide_BP/` as `BP`.
<FolderView :paths="[
'com.mojang/development_resource_packs/guide_RP/manifest.json',
'com.mojang/development_resource_packs/guide_RP/pack_icon.png',
'com.mojang/development_resource_packs/guide_RP/texts/en_US.lang',
'com.mojang/development_resource_packs/guide_RP/texts/languages.json',
'com.mojang/development_behavior_packs/guide_BP/manifest.json',
'com.mojang/development_behavior_packs/guide_BP/pack_icon.png',
'com.mojang/development_behavior_packs/guide_BP/texts/en_US.lang',
'com.mojang/development_behavior_packs/guide_BP/texts/languages.json',
]"></FolderView>
## What you have learned
:::tip What you have learned:
- What the com.mojang folder is, where it is and what folders it contains
- How to setup your workspace
- What a `manifest.json` file is
- How to use UUIDs
- How to create an icon for your addon
- What a `.lang` file is
:::
## Your progress so far
<Checklist>
- [x] Setup your pack
- [ ] Create a custom item
- [ ] Create a custom entity
- [ ] Create the entity's loot, spawn rules and a custom recipe
</Checklist>

179
docs/wiki/guide/software-preparation.md Normal file
View File

@@ -0,0 +1,179 @@
---
title: Software and preparation
category: Guide
description: How to setup your developement environment
nav_order: 3
prefix: '3. '
mentions:
- SirLich
- Dreamedc2015
- sermah
- cda94581
- Joelant05
- MedicalJewel105
- TheItsNameless
- TheDoctor15
- ChibiMango
- profeplaysminecraft
- solvedDev
- retr0cube
- SmokeyStack
- ThomasOrs
---
Before you can start creating addons, you first have to install the required tools and applications. While development will be easiest on Windows 10, we have provided mobile alternatives for both Android and iOS, where applicable.
## Download Minecraft Bedrock Edition
- [Windows 10](https://www.microsoft.com/en-us/p/minecraft-for-windows-10/9nblggh2jhxj?activetab=pivot:overviewtab)
- [Android](https://play.google.com/store/apps/details?id=com.mojang.minecraftpe&hl=en)
- [iOS](https://apps.apple.com/us/app/minecraft/id479516143)
- [Run MC on Linux](https://discord.gg/VJTZ3KaTx6)
## Picking an Editor
Addons can be created using any text editor, however it's much more comfortable to work in a dedicated editor. A good editor can give you code-completion, error-detection, and in-editor documentation.
There are strong opinions about the best editor for beginners, but generally speaking you cannot go wrong selecting either VSCode, or bridge. If you are mobile, you will need to use a mobile alternative.
### VSCode
VSCode is a general purpose text-editor and IDE. With VSCode, you will be able to edit your addons in plain-text, guided along by a powerful array of extensions and addons. VSCode is a great option for programmers and advanced users.
[⚙️Install VSCode](https://code.visualstudio.com/)
<Spoiler title="Configuring VSCode">
Many packages exist for VSCode that make editing addons easier:
- [Blockception's Minecraft Bedrock Development](https://marketplace.visualstudio.com/items?itemName=BlockceptionLtd.blockceptionvscodeminecraftbedrockdevelopmentextension)
- [.mcfunction support](https://marketplace.visualstudio.com/items?itemName=arcensoth.language-mcfunction)
- [.lang support](https://marketplace.visualstudio.com/items?itemName=zz5840.minecraft-lang-colorizer)
- [Bedrock Definitions](https://marketplace.visualstudio.com/items?itemName=destruc7i0n.vscode-bedrock-definitions)
- [Prettify-json](https://marketplace.visualstudio.com/items?itemName=mohsen1.prettify-json)
- [Spell Checker (for writing wiki)](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
- [Snowstorm Particle Editor](https://marketplace.visualstudio.com/items?itemName=JannisX11.snowstorm)
- [UUID Generator](https://marketplace.visualstudio.com/items?itemName=netcorext.uuid-generator)
</Spoiler>
### bridge.
[bridge.](https://bridge-core.app/) is a light-weight, dedicated IDE for Minecraft addons. It features [innovative features](https://bridge-core.app/guide/features/) such as [entity and block previews](https://bridge-core.app/guide/features/index.html#file-previews), [rich auto-completions and file validations](https://bridge-core.app/guide/features/index.html#auto-completions-and-validation) and [advanced file creation with presets](https://bridge-core.app/guide/features/index.html#advanced-file-creation).
bridge. includes a regular text editor for experienced addon creators and a tree editor to make it easy for beginners to get started with editing JSON files.
#### Next Steps
- [Read more on why you should use bridge.](https://bridge-core.app/guide/why-bridge)
- [Read our guide on getting started with bridge.](https://bridge-core.app/guide/index)
- [Try out bridge. online](https://editor.bridge-core.app/)
### Mobile Editors
#### Android
- [ACode Editor](https://play.google.com/store/apps/details?id=com.foxdebug.acodefree)
- [bridge. v2](https://bridge-core.app/)
#### iOS
- [Kodex](https://apps.apple.com/us/app/kodex/id1038574481)
- [bridge. v2](https://bridge-core.app/)
## Blockbench
- [Blockbench](https://blockbench.net/) is a 'boxy 3D model editor' typically used to create Minecraft models, textures and animations. Also provides a web-browser version which is compatible with mobile.
## Image Editors
When choosing an image editor, it is important to keep in mind that the traditional Minecraft style is composed of simple 16X16 pixelart. There are plenty of powerful and free art programs available for you to use. However, many of these programs have more tools than you will need for Minecraft graphical design and these tools require time to learn.
:::tip
Choose a program that feels comfortable and easy for you to use. Many Addon creators use different art programs for different tasks. (Example: One might use paint․net for most of the art, and piskel for Minecraft block animations). Choose what works best for you!
:::
### Krita
Krita is a powerful open-source art programed with the goal of giving free powerful digital art tools to artists. Krita has more than enough features to cover your Minecraft needs and works on a MAC or PC.
**+ Pros:** Plenty of features including a pixel brush with an intuitive user interface.
**- Cons:** Requires a little time to become familar with the tools.
[Download Krita](https://krita.org/en/)
### GIMP
Gimp is similar to Krita in that it is a free and open source digital art program that has a vast arrays of tools. Where Krita focuses more on illustration, GIMP focuses more on image manipulation (think Photoshop). Gimp also works on MAC or PC.
**+ Pros:** GIMP has more than enough tools for editing Minecraft art
**- Cons:** The interface is not intuitive. Even though GIMP is powerful, it requires a steep learning curve.
[Download Gimp](https://www.gimp.org/)
### Paint․net
Paint․net is a simple yet powerful image editing and art software. Paint․net may not have a vast array of tools like Krita and GIMP, but it does offer simplicity and ease of use.
**+ Pros:** Easy to use and learn.
**- Cons:** Only works on Windows.
[Download Paint.net](https://www.getpaint.net)
### Pixilart
Pixilart is a web-based pixel art software. It is extremely simple to use since it is focused on pixel art. It also has a powerful resize option that may come in handy, so that you can resize your art without losing the pixelart details.
**+ Pros:** Easy to use and learn. Curated specifically for pixel art.
**- Cons:** Must have internet connection. May be missing tools you want.
[Use Pixilart](https://www.pixilart.com/)
### Piskel
Piskel is a web-based pixel art software with a focus of making pixelated sprites (or video game character animations). This tool, similar to Pixilart, is simple to use. This is also a great tool for making flipbooks (Minecraft block or skin animations).
**+ Pros:** Easy to use and learn. Perfect for flipbook animations
**- Cons:** Must have internet connection. Only offers the most basic tools.
[Download Piskel](https://www.piskelapp.com/)
### Libresprite
LibreSprite is a free and open source program for creating and animating your sprites. Based on the last GPLv2 commit of aseprite.
**+ Pros**: Basic & easy to use, customizable and curated for pixel artists.
**- Cons**: May not work on Mac, maintained only by a small community.
## Additional Materials
:::tip
This guide will walk you through the first stages of addon development, but it is not comprehensive! To learn more about addons, you will have to use and reference other sources of information, which we will link to here.
:::
### Join the Discord
The best place to get help with this guide is to join the [discord server](/discord).
### Vanilla Packs
Minecraft's vanilla files are a good source of reference material. You should download these packs, and store them on a convenient location on your computer. When you need an example of an item, or entity, or animation, you can reference these files for inspiration.
- [Vanilla packs](https://github.com/Mojang/bedrock-samples/releases)
### Documentation
There are many good sources of Addon documentation. Familiarize yourself with all of them, and consider bookmarking them.
- [bedrock.dev](https://bedrock.dev/): Reference documentation.
- [wiki.bedrock.dev](https://wiki.bedrock.dev/): Tutorials and guides.
- [MS Docs](https://docs.microsoft.com/en-us/minecraft/creator/): The official microsoft creator portal for addons.
### Troubleshooting and Additional Help
- If the json format is very tricky for you, consider reading the [understanding-json guide](/guide/understanding-json).
- If you get stuck with an odd error, consider reading the [troubleshooting guide](/guide/troubleshooting).
- If you still haven't found a solution, feel free to join our [Discord server](/discord).
### Additional Links and Tools
- You can explore additional tools [here](/meta/useful-links).
## Your progress so far
<Checklist>
- [x] Installed the necessary software
- [x] Downloaded the Vanilla Example files
- [ ] Locate your `com.mojang` folder and create your addon's workspace.
- [ ] Create the manifest and pack icon for your first addon
</Checklist>

81
docs/wiki/guide/troubleshooting.md Normal file
View File

@@ -0,0 +1,81 @@
---
title: Troubleshooting
category: Extra
description: A simple troubleshooting guide
prefix: 'c. '
nav_order: 3
tags:
- help
mentions:
- SirLich
- Joelant05
- destruc7ion
- Dreamedc2015
- MedicalJewel105
- Luthorius
- SmokeyStack
---
Creating Addons for Bedrock Minecraft is a relatively straightforward process _once you get the hang of it_. The first time is usually a frustrating, bug-prone process. This document contains some tips and tricks for fixing those dastardly bugs, as well as best practice information.
Please read the whole page, before jumping into troubleshooting tips for a specific domain.
## Reload
First, you should always reload Minecraft. That means fully closing the game and then reopening it. This can catch many errors, especially those related to assets that are accessed via a filepath, such as textures or loot tables.
## The Environment
The best way to prevent nasty bugs is by working in the right environment. You should review the [software preparation document](/guide/software-preparation) for editor recommendations. The most important part is getting a JSON-linter, ([or using an online json-linter](https://jsonlint.com/)), and storing your packs in `development_behavior_packs` and `development_resource_packs`.
If you have your addons in the normal folders, you can run into "pack caching" issues, where you edit the files in one location, but the game is still using the old files.
## Content Log
:::warning Use the Content Log!
Content log is the best tool you have for debugging your addons. Please don't skip this step!
:::
::: tip
Errors are not cleared between runs, so the errors you see in the content log may be _old_ errors from prior runs.
:::
The 'Content Log' is a list of issues found in your pack. Minecraft will generate this list every time your load your world. It can catch issues such as:
- Wrong texture path
- Wrong spelled component
- Incorrect json structure
Content log can be turned on in in `Settings > Creator`. The content log will show in-game on load up, and if more errors occur during gameplay.
![](/assets/images/guide/content_log.png)
### Content Log File
The content log is saved in `.txt` format inside your files:
- *Windows*: `C:\Users\USERNAME\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\logs`
- *Android:* `/storage/emulated/0/Android/data/com.mojang.minecraftpe/files/games/com.mojang/logs`
## Using Vanilla Resources
You should download the vanilla resource and behavior pack. You can find the vanilla resource and behavior pack [here](https://www.minecraft.net/en-us/addons/). You can compare against the vanilla files if you have any issues!
## JSON-Schemas
JSON-Schemas are a valuable tool for file validation. You can learn more about JSON-Schemas [here](/meta/using-schemas).
# Troubleshooting your addon!
## Entities
<BButton link="/entities/troubleshooting-entities"> Troubleshoot your entities.</BButton>
## Items
<BButton link="/items/troubleshooting-items"> Troubleshoot your items.</BButton>
## Blocks
<BButton link="/blocks/troubleshooting-blocks"> Troubleshoot your blocks.</BButton>

151
docs/wiki/guide/understanding-json.md Normal file
View File

@@ -0,0 +1,151 @@
---
title: Understanding JSON
category: Extra
description: A first peek into JSON
nav_order: 1
prefix: 'a. '
mentions:
- SirLich
- solvedDev
- Joelant05
- Dreamedc2015
- sermah
- cda94581
---
::: tip
This is an appendix page. You can start the guide from the beginning [here](/guide/index).
:::
JSON is a simple format for writing text files, in a way that is understandable to both Humans and Computers. Bedrock uses .json files as the "language" of Add-Ons, so you will need a solid understand of how to read and write json! If you have never heard of JSON before, you are encouraged to read through [this tutorial](https://www.digitalocean.com/community/tutorials/an-introduction-to-json). It will teach you everything you need to know about writing valid JSON files.
## Valid JSON
The important thing to remember when writing JSON is that it must be _completely error free_, or it won't work at all. Even one wrong character, or one extra comma will cause the entire file to fail. For this reason, it's super important you write valid JSON.
We can use an online tool called [json lint](https://jsonlint.com/) to tell us whether our JSON is valid. Simply paste your code into the website, and press `Validate JSON`. You will get a response indicating whether your code is correct or not, as well as the location and type of any errors.
## Data Structures
In JSON, data can be written in a number of formats. Each format is specialized for the kind of data it wants to represent. Here are the structures we have available:
| Name | Example | Explanation |
| ------ | -------- | -------------------------------------- |
| String | "hello!" | Words, or characters. Requires quotes. |
| Int | 15 | A number. No quotes. |
| Float | 1.2 | A fractional number. No quotes. |
| Bool | true | Either true or false. No quotes. |
And now, in .json format:
```json
{
"my_string": "hello!",
"my_int": 15,
"my_float": 1.2,
"my_bool": true
}
```
In addition to these simple structures, we also have access to two special structures. Special structures are used to *nest* other data together.
### Arrays
Arrays are written as two square brackets `[]`. They represent a _list_. We can put _other data structures_ inside of the list. Each _element_ of the list should be separated by a comma.
Some examples:
| Structure | Comment |
| --------------- | ------------------------------------- |
| [1, 2, 3] | A list of integers. |
| ["Red", "blue"] | A list of strings. Notice the quotes! |
And now, in .json format:
```json
{
"my_ints": [1, 2, 3],
"my_strings": ["Red", "blue"]
}
```
### Objects
Objects are written as two curly-brackets `{}`. Objects are a special syntax which contains _named_ data structures. The name is called a `key`, and the structure is called a `value`. The examples earlier in this page was a *dictionary* containing examples of the other data types.
This key-value syntax looks like this: `"<key>": <any structure>`. Notice the quotes around the key, and the colon.
Here is an example of an object, which contains a few _key-value-pairs_.
<CodeHeader></CodeHeader>
```json
{
"a_list_of_integers": [1, 2, 3],
"is_json_cool": true
}
```
We need to separate each key-value pair with a comma.
We call the key-value pairs of an object as its _child_ or as being _inside_ the object.
## JSON Structure
In Minecraft, JSON files always begin with an _object_, which you can remember is two curly brackets:`{}`. We call this the _top level object_. We write our code _inside_ of this object, in the form of key-value pairs.
Here is an example of a simple json file, used for Minecraft addons:
<CodeHeader></CodeHeader>
```json
{
"format_version": "1.12.0",
"animations": {
"animation.car.wheel_spin": {
"loop": true,
"animation_length": 1.0,
"bones": {
"front_wheels": {
"rotation": ["q.modified_distance_moved * -30", 0, 0]
},
"back_wheels": {
"rotation": ["q.modified_distance_moved * -30", 0, 0]
}
}
}
}
}
```
Take a careful look at the format. You will see that the entire structure is built out the data-structures that we have already learned. If you want to practice your json skills, try to answer these questions:
- How many keys are there in the _top level object_. Can you name them?
- What is the value of `format_version`?
- What kind of data is stored in the `"loop"` key? (string, boolean, etc)
## Troubleshooting Examples
Here are a few examples, to help you understand feedback you might recieve on the discord or online. We tend to use technical jargon when talking about errors in JSON, so hopefully this section helps familizrize you with the terms:
---
You wrote: `"format_version": 1.12`
They said: "_The value for format_version is the wrong type. It should be a string._
Remember that `type` means one of the structures: `String`, `Int`, `Float`, `Array` or `Object`. If we examine our code, we will see that we put `format_version` to a `Float`, instead of a `String`. We can fix this problem by adding quotes around the `"1.12"`.
---
You wrote: `[1 2 5 6]`
They said: "_Your array is missing commas._"
Remember that array elements need to be separated by commas. Your array should look like this: `[1, 2, 5, 6]`
---
They said: _"You accidentally put the format version inside your description. It should go outside at the top level_".
This means that the key-value pair for `"format_version"` as a _child_ of the description. You should copy/paste the key-value pair out from the description object, and place it at the top level.

251
docs/wiki/items/attachables.md Normal file
View File

@@ -0,0 +1,251 @@
---
title: Attachables
category: Documentation
tags:
- beginner
mentions:
- Sprunkles317
- MedicalJewel105
- AdamRaichu
- Luthorius
- TheItsNameless
---
::: tip
This document assumes you have a basic understanding of Molang, render controllers, animations, and client entity definitions. Ensure you are familiar with the basics of [client entities](/entities/entity-intro-rp)!
:::
## Introduction
When we design a custom item or block, Minecraft will build a model from a template so the item can be displayed when held. This takes the form of the item's sprite being an extruded texture mesh, or blocks displaying with their model. By using a system called **attachables** we can design our own models to be displayed when these items are held.
Ever wanted sticks to look like spyglasses? Or to wield a big chainsaw with a spinning chain? Attachables are the way to accomplish that!
This document covers **two different ways** to create attachables, depending on how the geometry being used is constructed.
## Overview
Attachables are a system of rendering entity models when an item or block is equipped. This means having the item held in the main hand, off hand, or armor slots.
Attachable definitions are quite similar in design to client entity definitions; they let us define textures, materials, geometries, and animations to display the attachable.
### File Structure
The attachable definition goes within the 'attachables' folder. The file layout is otherwise identical to that of custom entities.
<FolderView
:paths="[
'RP/animations/my_item.animation.json',
'RP/attachables/my_item.entity.json',
'RP/models/entity/my_item.geo.json',
'RP/textures/entity/my_item.png',
'RP/manifest.json'
]"
></FolderView>
### Attachable Definition
Here's a basic example of an attachable.
<CodeHeader>RP/attachables/stick.entity.json</CodeHeader>
```json
{
"format_version": "1.10.0",
"minecraft:attachable": {
"description": {
"identifier": "minecraft:stick",
"materials": {
"default": "entity",
"enchanted": "entity_alphatest_glint"
},
"textures": {
"default": "textures/entity/steve",
"enchanted": "textures/misc/enchanted_item_glint"
},
"geometry": {
"default": "geometry.wiki.steve_head"
},
"animations": {
"hold_first_person": "animation.steve_head.hold_first_person",
"hold_third_person": "animation.steve_head.hold_third_person"
},
"scripts": {
"animate": [
{
"hold_first_person": "context.is_first_person == 1.0"
},
{
"hold_third_person": "context.is_first_person == 0.0"
}
]
},
"render_controllers": [
"controller.render.item_default"
]
}
}
}
```
A few key things to point out with this attachable definition:
- The identifier matches an existing block or item ID. This will activate the attachable when the item is equipped, and will replace the original model that appears when held.
- There is a material and texture listed for the enchantment glint. This is important to keep around if your item should have the glint when enchanted.
Making attachables is a little more involved than making a client entity file. We need to properly rig the geometry's skeleton so that it looks correct when equipped.
## Method 1 - Attached to the Skeleton
<Label name="Beginner" color="blue"></Label>
In this first method we will construct the attachable using a copy of the player's skeleton, by attaching your model to one of the player's bones.
This solution is ideal for models that are intended for scenarios involving only one type of mob/entity, especially players; and involving only one equipment slot. It is easy to view what the model will look like in Blockbench.
### Setting up the Skeleton
We need to reconstruct the player's skeleton in order for our model to be parented to the correct bone, otherwise it will not be parented to anything and will float freely on the player.
With a text editor, take the bones from the provided player skeleton file and copy them to your geometry file, then set the `rightItem` bone as the parent to the cubes from your model. Save this geometry to your resource pack.
For convenience, such a model has been prepared here. The cubes from the player's model have already been removed:
<BButton
link="https://github.com/Bedrock-OSS/bedrock-wiki/blob/wiki/docs/public/assets/packs/tutorials/attachables/method_one/steve_head.geo.json?raw=true"
color=blue
>📄 Geometry File</BButton>
### Display Settings
Having your model floating at the player's feet is not ideal. Our next step is to create animations so we can properly display the model on the player.
Create two new animations, one for holding the item in first person and another for holding it in third person. Select your third-person animation, and position it however you want. Save this animation to your resource pack.
Here is an example of such an animation. This also includes a first-person animation—the means of making one is detailed in the section below.
<BButton
link="https://github.com/Bedrock-OSS/bedrock-wiki/blob/wiki/docs/public/assets/packs/tutorials/attachables/method_one/steve_head.animation.json?raw=true"
color=blue
>📄 Animation File</BButton>
### First-person Animations
To more easily create first-person animations, we need to mimic how the arm is positioned in the first person.
:::tip
To add animation for player's hands, you need to use player's animations, not attachables animations.
:::
Use the following guide animation and import it into Blockbench. It applies a rotation of (95, -45, 115) and a translation of (13.5, -10, 12) to the right arm bone, perfectly mimicking how the arm is positioned in first-person.
<BButton
link="https://github.com/Bedrock-OSS/bedrock-wiki/blob/wiki/docs/public/assets/packs/tutorials/attachables/method_one/attachable_guide.animation.json?raw=true"
color=blue
>📄 Attachable Guide File</BButton>
:::warning NOTE
This is where things get tricky. Both animations will need to be played simultaneously; your first-person animation, and the guide's first-person animation.
Be sure you are editing your animation when making your changes. Select it first, then play the guide's first-person animation on top.
:::
### Conclusion
With this all set up, go through and delete the *cubes* from the player skeleton if there are any, but keep the bones. Check the model out in-game!
## Method 2 - Bound to a Bone
<Label name="Intermediate" color="orange"></Label>
In this second method, the attachable geometry will be constructed using model binding. This allows a model to be directly attached to a bone within a mob's geometry corresponding to the slot it is equipped in. Minecraft employs model binding for its attachable items, including the trident, spyglass, bow, and shield.
While this method allows the attachable to apply more dynamically to other mobs and equipment slots, model binding also has strange quirks, which will be illustrated below. Some developers may find this method trickier to get working.
### Model Binding
Our first step is to upgrade the model file format version to `"1.16.0"` if it is not already. If the model is a legacy file, then convert it before continuing; Blockbench has a tool to do this (File → Convert Project).
Next up is modifying the root bone of our geometry to be bound to the equipment slot the item is placed in. Take note of line 4 in this excerpt from the skeleton head geometry file:
<CodeHeader>RP/models/entity/skeleton_head.geo.json</CodeHeader>
```json
// A bone
{
"name": "skeleton_head",
"binding": "q.item_slot_to_bone_name(context.item_slot)",
"pivot": [0, 4, 0],
"cubes": [
{
"origin": [-4, 0, -4],
"size": [8, 8, 8],
"uv": [0, 0]
}
]
}
```
The `"parent"` key in a bone accepts a string, and whichever bone name is entered will be set as the parent to the current bone; the child bones keep their positions but move relative to the parent bone.
The `"binding"` key on the other hand accepts Molang, and the pivot point of whichever bone name is entered is set as the *root position* that the child bone and its children should inherit.
For the value of `"binding"` we are using the Molang query `q.item_slot_to_bone_name`, which converts a slot name to a bone name, with the contextual variable `context.item_slot` as an argument. This converts the name of the equipment slot this item resides in to its corresponding bone name in the player's geometry. The conversions are as follows:
- `'main_hand'` → "rightitem"
- `'off_hand'` → "leftitem"
Apply the model binding to your bone, and save the geometry to your resource pack.
An example model with this binding applied is provided here:
<BButton
link="https://github.com/Bedrock-OSS/bedrock-wiki/blob/wiki/docs/public/assets/packs/tutorials/attachables/method_two/skeleton_head.geo.json?raw=true"
color=blue
>📄 Geometry File</BButton>
### Display Settings
With that done, the next step is to set up animations to display the model in first person and third person.
Create two new animations, one for holding the item in first person and another for holding it in third person.
To make creating these animations easier, please do the following:
- Download the following player skeleton model. We will use this as a visual aid for positioning your model.
<BButton
link="https://github.com/Bedrock-OSS/bedrock-wiki/blob/wiki/docs/public/assets/packs/tutorials/attachables/method_two/player_skeleton.geo.json?raw=true"
color=blue
>📄 Player Skeleton File</BButton>
- With a text editor, add the bones and cubes from your model to the player skeleton model, then import the player skeleton model into Blockbench.
- Set your model's root bone(s) to be a child of the 'rightItem' bone in the player skeleton.
- Download the following animation file import the `wiki.third_person_guide` animation. This will be used later to make positioning easier.
<BButton
link="https://github.com/Bedrock-OSS/bedrock-wiki/blob/wiki/docs/public/assets/packs/tutorials/attachables/method_two/attachable_guide.animation.json?raw=true"
color=blue
>📄 Attachable Guide File</BButton>
These guide animations have one notable feature: they apply a -24 offset to the y-position of the right item bone to counteract a similar -24 y-position offset Minecraft applies to bound bones. We are unsure at this time why this happens.
:::warning NOTE
Similar to Method One, **two** animations will need to be played simultaneously for correct positioning.
Be sure you are editing your animations when making your changes. Select it first, then play the guide animation on top.
:::
Play both animations, and position your model however you want. Save the animations to your resource pack.
An example animation file for this positioning:
<BButton
link="https://github.com/Bedrock-OSS/bedrock-wiki/blob/wiki/docs/public/assets/packs/tutorials/attachables/method_two/skeleton_head.animation.json?raw=true"
color=blue
>📄 Animation File</BButton>
### First-person Animations
Similar to the third-person animation, look in the Attachable Guide file and import the `wiki.first_person_guide` animation into Blockbench. Play both your animation and the guide's first-person animation together, then make your changes and save the file.
## Example Pack
Each of these methods have been compiled into an example pack you may reference, for if you are getting stuck or simply want to see a working example.
<BButton
link="https://github.com/Bedrock-OSS/wiki-addon/releases/download/download/attachable-example.mcpack"
color=blue
>💾 Example Pack</BButton>

562
docs/wiki/items/custom-armor.md Normal file
View File

@@ -0,0 +1,562 @@
---
title: Custom Armor
category: Tutorials
tags:
- experimental
mentions:
- SirLich
- Dreamedc2015
- sermah
- yanasakana
- Joelant05
- MedicalJewel105
- aexer0e
- Brougud
- XxPoggyisLitxX
- LeGend077
- SmokeyStack
---
::: tip
It is highly recommended that you look over [the BlockBench modelling and texturing](/guide/blockbench) section in the beginners guides before tackling these sections.
:::
Making custom armors is surprisingly easy to do, you need to do a bit of fiddling around as there are a few files that need to be added and there can be a little bit of texturing involved but you can do as much or as little as you want here.
## Chest Piece
Create a chest piece:
<CodeHeader>BP/items/my_chest.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "wiki:my_chest",
// Notice we give it the equipment category
"category": "equipment"
},
"components": {
// Make sure it appears within the chestplate category
"minecraft:creative_category": {
"parent": "itemGroup.name.chestplate"
},
// The icon we want to use in our INVENTORY
"minecraft:icon": {
"texture": "my_chest"
},
// We give it a name
"minecraft:display_name": {
"value": "My Custom Armor"
},
// We dont want it to stack
"minecraft:max_stack_size": 1,
// We make sure it can only receive enchantments for chest pieces
"minecraft:enchantable": {
"value": 10,
"slot": "armor_torso"
},
// This tells it how much protection it should give
"minecraft:armor": {
"protection": 5
},
// We want it to be repairable, and what to use to repair it
"minecraft:repairable": {
"repair_items": [
{
"items": ["minecraft:stick"],
"repair_amount": "context.other->q.remaining_durability + 0.05 * context.other->q.max_durability"
// Some complicated molang; just copy it
}
]
},
// Mark it as a wearable and that it goes in the chest slot
"minecraft:wearable": {
"dispensable": true,
"slot": "slot.armor.chest"
},
// Provide its durability
"minecraft:durability": {
"max_durability": 200
}
}
}
}
```
At this point you could just go and add an item texture into your `RP/textures/item_texture.json` with the key `my_chest` and you are on your way. We have attached a default item texture for your armor here if you want to just follow along.
![](/assets/images/tutorials/custom-armor/custom_chestplate.png)
<BButton link="https://raw.githubusercontent.com/Bedrock-OSS/bedrock-wiki/wiki/docs/public/assets/images/tutorials/custom-armor/custom_chestplate.png">Download texture here</BButton>
## Adding attachables and textures
At this point your item would appear in game and would be wearable but it would not have any appearance. This is because we need to tell it how to handle the attachable equipment and give it a texture to show.
To start with you need to create an `attachables` folder in your RP (you may already have one).
<CodeHeader>RP/attachables/my_chest.json</CodeHeader>
```json
{
"format_version": "1.8.0",
"minecraft:attachable": {
"description": {
"identifier": "wiki:my_chest",
// These 2 are default and are required
"materials": {
"default": "armor",
"enchanted": "armor_enchanted"
},
"textures": {
// This is our CUSTOM armor texture we need to make next
"default": "textures/models/armor/custom_main",
// This texture doesn't actually exist in our RP
// but it will blow up without it so leave it in
"enchanted": "textures/misc/enchanted_item_glint"
},
// We tell it what geometry to use for the chestplate
"geometry": {
"default": "geometry.player.armor.chestplate"
},
// We tell it to hide the chest layer as we will be showing our armor on top
"scripts": {
"parent_setup": "v.chest_layer_visible = 0.0;"
},
// We tell it what controller to use (default armor one)
"render_controllers": ["controller.render.armor"]
}
}
}
```
At this point we need to make sure we create a texture for our model, these live in `RP/textures/models/armor`. We however actually need 2 textures, as one is for the main armor as if it is being worn all together, and one is for the legs which when worn alone will often cover some of the boot area.
If you do not feel creative we have provided a recoloured diamond armour skin for use with this tutorial. So just `Save As` and plop them in the folder.
![](/assets/images/tutorials/custom-armor/custom_main.png)
<BButton link="https://raw.githubusercontent.com/Bedrock-OSS/bedrock-wiki/wiki/docs/public/assets/images/tutorials/custom-armor/custom_main.png">Download texture here</BButton>
![](/assets/images/tutorials/custom-armor/custom_legs.png)
<BButton link="https://raw.githubusercontent.com/Bedrock-OSS/bedrock-wiki/wiki/docs/public/assets/images/tutorials/custom-armor/custom_legs.png">Download texture here</BButton>
> In the real world you would probably want to use `BlockBench` or some photo editing program to edit the textures and ideally see how they look on a model before you add them into the addon.
> If you now go into the game and check what you have produced you should be able to wear your chest piece and pat yourself on the back for a job well done.
![](/assets/images/tutorials/custom-armor/armor-item-image.jpg)
![](/assets/images/tutorials/custom-armor/armor-model-image.jpg)
## Leggings
So while the chest piece alone is great, you probably want a whole set, so from here if you make another item json for the boots like so.
<CodeHeader>BP/items/my_leggings.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "wiki:my_leggings",
"category": "equipment"
},
"components": {
// We give it the leggings category this time
"minecraft:creative_category": {
"parent": "itemGroup.name.leggings"
},
// Give it an applicable ITEM texture
"minecraft:icon": {
"texture": "my_leggings"
},
"minecraft:display_name": {
"value": "My Custom Leggings"
},
"minecraft:max_stack_size": 1,
// Make sure the enchantments are for legs
"minecraft:enchantable": {
"value": 10,
"slot": "armor_legs"
},
"minecraft:armor": {
"protection": 3
},
"minecraft:repairable": {
"repair_items": [
{
"items": ["minecraft:stick"],
"repair_amount": "context.other->q.remaining_durability + 0.05 * context.other->q.max_durability"
}
]
},
// Make sure the wearable slot is legs
"minecraft:wearable": {
"dispensable": true,
"slot": "slot.armor.legs"
},
"minecraft:durability": {
"max_durability": 200
}
}
}
}
```
This is great and like before you will need to add your own item texture, although here is one if you just want to continue.
![](/assets/images/tutorials/custom-armor/custom_leggings.png)
<BButton link="https://raw.githubusercontent.com/Bedrock-OSS/bedrock-wiki/wiki/docs/public/assets/images/tutorials/custom-armor/custom_leggings.png">Download texture here</BButton>
Once we are done here we need to create the attachables file like this:
<CodeHeader>RP/attachables/my_leggings.json</CodeHeader>
```json
{
"format_version": "1.8.0",
"minecraft:attachable": {
"description": {
"identifier": "wiki:my_leggings",
// Notice this is the same as before
"materials": {
"default": "armor",
"enchanted": "armor_enchanted"
},
"textures": {
// Same as before
"enchanted": "textures/misc/enchanted_item_glint",
// This one is different as we are using the legging specific texture
"default": "textures/models/armor/custom_legs"
},
// Tell it to use leggings geom
"geometry": {
"default": "geometry.humanoid.armor.leggings"
},
// Hide legs layer as we will be rendering over it
"scripts": {
"parent_setup": "v.leg_layer_visible = 0.0;"
},
// Same as before
"render_controllers": ["controller.render.armor"]
}
}
}
```
Given that we have already put in the textures needed we can run it and see our legs straight away.
## Helmet
This is just like the chest piece, just we change some of the categories and slots like so.
<CodeHeader>BP/items/my_helm.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "wiki:my_helm",
"category": "equipment"
},
"components": {
// Helmet category
"minecraft:creative_category": {
"parent": "itemGroup.name.helmet"
},
"minecraft:icon": {
"texture": "my_helm"
},
"minecraft:display_name": {
"value": "My Custom Helmet"
},
"minecraft:max_stack_size": 1,
// Helm enchantment slot
"minecraft:enchantable": {
"value": 10,
"slot": "armor_head"
},
"minecraft:armor": {
"protection": 3
},
"minecraft:repairable": {
"repair_items": [
{
"items": ["minecraft:stick"],
"repair_amount": "context.other->q.remaining_durability + 0.05 * context.other->q.max_durability"
}
]
},
// Wearable head slot
"minecraft:wearable": {
"dispensable": true,
"slot": "slot.armor.head"
},
"minecraft:durability": {
"max_durability": 200
}
}
}
}
```
As you can see not much has changed, we just update the categories/slots to the correct ones for helms and then we add the attachables file (here is the item texture if you need it).
![](/assets/images/tutorials/custom-armor/custom_helmet.png)
<BButton link="https://raw.githubusercontent.com/Bedrock-OSS/bedrock-wiki/wiki/docs/public/assets/images/tutorials/custom-armor/custom_helmet.png">Download texture here</BButton>
<CodeHeader>RP/attachables/my_helm.json</CodeHeader>
```json
{
"format_version": "1.8.0",
"minecraft:attachable": {
"description": {
"identifier": "wiki:my_helm",
// These 2 are default and are required
"materials": {
"default": "armor",
"enchanted": "armor_enchanted"
},
"textures": {
// This is our CUSTOM armor texture we need to make next
"default": "textures/models/armor/custom_main",
// This texture doesn't actually exist in our RP
// but it will blow up without it so leave it in
"enchanted": "textures/misc/enchanted_item_glint"
},
// We tell it what geometry to use for the helmet
"geometry": {
"default": "geometry.player.armor.helmet"
},
// We tell it to hide the helmet layer as we will be showing our armor on top
"scripts": {
"parent_setup": "v.chest_layer_visible = 0.0;"
},
// We tell it what controller to use (default armor one)
"render_controllers": ["controller.render.armor"]
}
}
}
```
There you go, you now have 3/4 of a complete set, we may as well go through the boots as well so you know all the categories etc.
## Boots
You already know the pattern so lets make the item and attachable json files.
<CodeHeader>BP/items/my_boots.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "wiki:my_boots",
"category": "equipment"
},
"components": {
// Boots category
"minecraft:creative_category": {
"parent": "itemGroup.name.boots"
},
"minecraft:icon": {
"texture": "my_boots"
},
"minecraft:display_name": {
"value": "My Custom Boots"
},
"minecraft:max_stack_size": 1,
// Enchantable Feet
"minecraft:enchantable": {
"value": 10,
"slot": "armor_feet"
},
"minecraft:armor": {
"protection": 3
},
"minecraft:repairable": {
"repair_items": [
{
"items": ["minecraft:stick"],
"repair_amount": "context.other->q.remaining_durability + 0.05 * context.other->q.max_durability"
}
]
},
// Feet slot
"minecraft:wearable": {
"dispensable": true,
"slot": "slot.armor.feet"
},
"minecraft:durability": {
"max_durability": 200
}
}
}
}
```
The custom boots texture if you need it.
![](/assets/images/tutorials/custom-armor/custom_boots.png)
<BButton link="https://raw.githubusercontent.com/Bedrock-OSS/bedrock-wiki/wiki/docs/public/assets/images/tutorials/custom-armor/custom_boots.png">Download texture here</BButton>
<CodeHeader>RP/attachables/my_boots.json</CodeHeader>
```json
{
"format_version": "1.8.0",
"minecraft:attachable": {
"description": {
"identifier": "wiki:my_boots",
// These 2 are default and are required
"materials": {
"default": "armor",
"enchanted": "armor_enchanted"
},
"textures": {
// This is our CUSTOM armor texture we need to make next
"default": "textures/models/armor/custom_main",
// This texture doesn't actually exist in our RP
// but it will blow up without it so leave it in
"enchanted": "textures/misc/enchanted_item_glint"
},
// We tell it what geometry to use for the boots
"geometry": {
"default": "geometry.player.armor.boots"
},
// We tell it to hide the boots layer as we will be showing our armor on top
"scripts": {
"parent_setup": "v.chest_layer_visible = 0.0;"
},
// We tell it what controller to use (default armor one)
"render_controllers": ["controller.render.armor"]
}
}
}
```
Thats it, you now have a whole suit of custom armor you can swagger around in, and use this as a basis to make whatever other armors you want in the game.
> It is worth noting that we have used 2 separate textures here, and you could potentially use a texture per attachable, but each new texture consumes memory so its best to use as few as possible.
> So this is what you should end up with, and as a bonus there is one more section on making set effects using filters, which is a bit more advanced but its a fun thing to do.
![](/assets/images/tutorials/custom-armor/custom-set-image.jpg)
## Bonus - Making Set Effects
This is a bit more advanced but lets say you want your custom armor to act like it's a set from an RPG game. We can add some code to check if we have the set equipped and do some great stuff with it.
Note that for effects you can use tick.json and functions with hasitem selector argument to avoid using player.json.
In this example we will just add a chance to teleport the attacker somewhere nearby and put a blurb on the console for flavour.
As we want this to trigger when the player is hit we need to add some logic to the `player.json` file. This is a huge file and we unfortunately need to make sure it has all the default content in there as well due to the way it will overwrite the default player components etc.
So rather than include the whole `player.json` I will just include the parts you will need to add to your `components` and `events` sections. If you have no idea what the `player.json` is then look in the vanilla behavior pack and look for it and just copy it over into your project.
So first of all lets put in the damage sensor component (which goes in your component section) which listens for when you take damage and lets you raise an event from it.
<CodeHeader>BP/entities/player.json#components</CodeHeader>
```json
"minecraft:damage_sensor": {
"triggers": {
"on_damage": {
"filters": {
"all_of": [
{
"test": "has_equipment",
"subject": "self",
// Domain is the body part in this case
"domain": "head",
"operator": "==",
// The item identifier we want to check
"value": "wiki:my_helm"
},
{
"test": "has_equipment",
"subject": "self",
"domain": "torso",
"operator": "==",
// Worth noting you can omit prefix for minecraft internal items i.e stick
"value": "wiki:my_chest"
},
{
"test": "has_equipment",
"subject": "self",
"domain": "leg",
"operator": "==",
"value": "wiki:my_leggings"
},
{
"test": "has_equipment",
"subject": "self",
"domain": "feet",
"operator": "==",
"value": "wiki:my_boots"
}
]
},
// If all the triggers match in the filter raise the event
"event": "wiki:armor_sets.my_custom.taken_damage"
},
// This means if it matches the check it still applies damage
// Can be good to ignore team damage or similar scenarios
"deals_damage": true
}
}
```
As you can see from the comments, there is a lot there but really all we are doing is listening out for something then making sure we only filter the results we care about then relay on an event.
> The event can be called anything but it is often better to have it more specific, incase you end up having multiple similar events etc, also it can help finding if you have multiple sections to it, i.e I could search on "armour_sets" and find all events related to it.
> Then once you are done, in the same file we decide what we want to do with the event, which we put into our `events` section.
<CodeHeader>BP/entities/player.json#events</CodeHeader>
```json
"wiki:armor_sets.my_custom.taken_damage": {
"randomize": [
{
"weight": 1,
// We do a sequence here as we want to apply one command
// on one entity and the other on ourselves
"sequence": [
{
// This will take the attacker/other because it was in context
// at time of raising the event in the damage_sensor
"run_command": {
// Teleport the entity away from us
"command": "spreadplayers ~~ 5 20 @s",
// Run the command on the attacker not us
"target": "other"
}
},
{
"run_command": {
"command": "tellraw @s{\"rawtext\":[{\"text\":\"§aYour Armor Glows And The Enemy Vanishes\"}]}"
}
}
]
},
{
// Dummy weighting so it happens semi frequently
"weight": 20
}
]
}
```
Thats it, you can rejig the bits how you see fit but ultimately you have all the pieces to apply effects to armor and check for if you have the whole set applied or check for other equipment.
You can also change the equipment checks from self to other and check if whoever is attacking you has something equipped or even check if you are attacking a sort of block/entity and do different effects based on that. We haven't touched on that directly here but there is a good enough starting point to get you on your way and let you be creative with things.

277
docs/wiki/items/custom-weapon.md Normal file
View File

@@ -0,0 +1,277 @@
---
title: Custom Weapons
category: Tutorials
tags:
- experimental
mentions:
- SirLich
- solvedDev
- MedicalJewel105
- aexer0e
- PepijnMC
- ThomasOrs
- Xterionix
---
Making a custom weapon is pretty simple since the 1.16.100 changes, as these allow you to simply define an item entry for it in your `BP/items` folder and provide a corresponding texture in the `RP/textures/items` folder with a bit of config and you have a fully working weapon that you can customize however you see fit.
## Custom Sword Item
Like with the other item tutorials we will start by making a simple custom sword like so.
<CodeHeader>BP/items/my_sword.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "wiki:my_sword",
// Notice we give it the equipment category
"category": "equipment"
},
"components": {
// This allows us to have the sword in the creative category of swords
"minecraft:creative_category": {
"parent": "itemGroup.name.sword"
},
"minecraft:max_stack_size": 1,
// This is a new change as we want it to be equippable in the hand
"minecraft:hand_equipped": true,
"minecraft:durability": {
"max_durability": 600
},
// Give it however much damage you want
"minecraft:damage": 10,
// We also let it be enchantable in the "sword" slot
"minecraft:enchantable": {
"value": 10,
"slot": "sword"
},
// This texture is used for both inventory and the hand model
"minecraft:icon": {
"texture": "my_sword"
},
"minecraft:display_name": {
"value": "My Custom Sword"
},
// Allow the sword to be repaired with sticks
"minecraft:repairable": {
"repair_items": [
{
"items": ["minecraft:stick"],
"repair_amount": "context.other->q.remaining_durability + 0.05 * context.other->q.max_durability"
}
]
}
}
}
}
```
So at a bare minimum that is enough to get a sword put into the game, we still need to register the icon with the RP but thats not a massive issue as all we need to do is go to our RP folder and enter it in like so.
<CodeHeader>RP/textures/item_texture.json</CodeHeader>
```json
{
"resource_pack_name": "vanilla",
"texture_name": "atlas.items",
"texture_data": {
"my_sword": {
// Make sure you have put an icon texture called my_sword.png here
"textures": "textures/items/my_sword"
}
}
}
```
Here is an example texture if you do not have your own to use, just `Save As` and plop it in the `RP/textures/items` directory.
![](/assets/images/tutorials/custom-weapons/my_sword.png)
<BButton link="https://raw.githubusercontent.com/Bedrock-OSS/bedrock-wiki/wiki/docs/public/assets/images/tutorials/custom-weapons/my_sword.png">Download texture here</BButton>
## In-game
So now we have a BP containing our items json data and an RP containing the texture, we can make a new level, and make sure we include our BP/RP, however we **also need to enable the Holiday Creator Features** under experimental gameplay.
Once you have done all the above, go into creative mode and you should be able to find your sword by its name, or under the sword category as shown.
![](/assets/images/tutorials/custom-weapons/custom_sword.jpg)
Then if you put it in your hands you should see it in the game like this.
![](/assets/images/tutorials/custom-weapons/held_sword.jpg)
Now that wasn't too hard was it! and you can make as many custom swords as you want now, however there is far more fun stuff you can do from here if you feel up for it.
## Tool-like Functionality
You can also mix and match other components like `minecraft:digger` to allow you to go through web or bamboo quicker like this:
<CodeHeader>BP/items/my_sword.json#components</CodeHeader>
```json
"minecraft:digger": {
"use_efficiency": true,
"destroy_speeds": [
{
"block": "minecraft:web",
"speed": 15
},
{
"block": "minecraft:bamboo",
"speed": 10
}
],
"on_dig":{
"event": "wiki:my_sword.on_dig_damage"
//Needed to change sword durability
}
}
```
Also add an event:
<CodeHeader>BP/items/my_sword.json</CodeHeader>
```json
"events": {
"wiki:my_sword.on_dig_damage": {
"damage":{
//This part of event will make sword take damage when it was used to dig block
"type":"durability",
"target":"self",
//By using "self" you define item as target to take damage
"amount":1
}
}
}
```
You can also give it a default mining speed by adding `"minecraft:mining_speed": 1.5`, which would give it a generic mining speed letting you use your weapon like a pickaxe.
(It is currently broken)
## Damage Tooltip
The above was a bare bones approach, but you probably want to be able to show the damage a sword does when the user hovers over it.
To do this you need to add the `"minecraft:weapon": {}` component, even if its just empty this is enough to MC to know internally to treat your popup like a weapon popup when mouse over-ing.
So if you add the above component to your item json file when you mouse over your sword you will now see **+10 Attack Damage** listed in its tooltip.
> You may be thinking "why didn't you just add this above?" and the answer is because we will build off this component to add more cool stuff in the next section, so I wanted to keep it separate.
## Unique ability & durability
At this point you could call it a day, but what if you wanted to make a sword that could inflict status effects, or teleport an enemy when they attacked you?
Assuming you wanted to do something like this we will need to build off the `minecraft:weapon` component and raise an event when the weapon hits an entity.
<CodeHeader>BP/items/my_sword.json#components</CodeHeader>
```json
"minecraft:weapon": {
"on_hurt_entity": {
"event": "wiki:my_sword.hurt_entity"
}
}
```
Once we add that then every time you hurt an entity it will raise the event `wiki:my_sword.hurt_entity`. You can name this whatever you want, but if you end up with lots of events its recommended to have some level of namespacing, so in this scenario `example` is my main namespace, `my_sword` is the item I want it to apply on and `hurt_entity` is the related event on that item.
> I could just as easily call the event **"space-noodle"** and it would work fine, but you want it to be easily searchable and self explaining, so keep that in mind
Now that we have an event being raised we can do what we want with it. In this example I am going to do 3 things:
1. Teleport the player with 25% chance.
2. Output a message letting the player know that something happened.
3. Damage the sword.
So if you go back into your my_sword.json and after your `components` section add a new section like so.
<CodeHeader>BP/items/my_sword.json</CodeHeader>
```json
"events": {
"wiki:my_sword.hurt_entity": {
"sequence":[
//Sequence is needed to run two or more parts of event
{
"randomize": [
{
// Weights are relative, so this has 1
"weight": 1,
// Teleport the HOLDER (you) within an 8x8x8 range
"teleport": {
"target": "holder",
"max_range": [8,8,8]
},
// Then tell some green text
"run_command":{
"command":[
"tellraw @s{\"rawtext\":[{\"text\":\"§aYour Sword Glows§r\"}]}"
]
}
},
{
// We have another dummy random element here which contains the max weight
"weight": 3
}
]
},
{
// I think you haven't forgot what this do
"damage":{
"type":"durability",
"target":"self",
"amount":1
}
}
]
}
}
```
That was a bit to bite off, but as explained above this lets us randomly **1/4** of the time trigger a teleportation of the sword holder and show a text command when it happens.
You can do whatever you want here and get super creative, set enemies on fire, or spawn enemies or blocks etc. There is so much you can do with this basic approach to creating weapons!
> It's worth noting here that the dummy element is needed to scale the weightings, so we have one element with a weight of **1** and a 2nd one with a weight of **4** so this gives us the **1 in 4** chance of it proccing. If we were to have gone with the dummy element having a weight of **100** then we would have a **1 in 100** chance of proccing. If we didn't have a 2nd dummy element then the first weight would be ignored and it would happen 100% of the time.
## Anything Else?
You should probably make a recipe for it, which is covered in previous chapters, as there isn't anything really new in there, but incase you are unsure here is an example one to make the sword with ender eyes and ender pearls.
<CodeHeader>BP/recipes/my_sword.json</CodeHeader>
```json
{
"format_version": "1.12.0",
"minecraft:recipe_shaped": {
"description": {
"identifier": "wiki:my_sword"
},
"tags": ["crafting_table"],
"pattern": ["e", "E", "#"],
"key": {
"#": {
"item": "minecraft:stick"
},
"E": {
"item": "minecraft:ender_eye"
},
"e": {
"item": "minecraft:ender_pearl"
}
},
"result": {
"item": "wiki:my_sword"
}
}
}
```
![](/assets/images/tutorials/custom-weapons/sword_recipe.jpg)
If you whack that in then you can now craft your sword in the game and hopefully go off and make any other custom swords you fancy or even bows or tridents.

54
docs/wiki/items/enchantments.md Normal file
View File

@@ -0,0 +1,54 @@
---
title: Enchantments
category: Documentation
nav_order: 5
tags:
- Stable
- Last updated for Version 1.18.10
mentions:
- Ciosciaa
- MedicalJewel105
- SmokeyStack
---
Enchantment identifiers are used in the `/enchant` command and in item functions and conditions.
| Name | Identifier | Maximum Level | Treasure | Curse |
| ----------------------- | ----------------------- | ------------- | -------- | ----- |
| Silk Touch | `silk_touch` | 1 | ❌ | ❌ |
| Fortune | `fortune` | 3 | ❌ | ❌ |
| Efficiency | `efficiency` | 5 | ❌ | ❌ |
| Luck of the Sea | `luck_of_the_sea` | 3 | ❌ | ❌ |
| Lure | `lure` | 3 | ❌ | ❌ |
| Sharpness | `sharpness` | 5 | ❌ | ❌ |
| Smite | `smite` | 5 | ❌ | ❌ |
| Bane of Arthropods | `bane_of_arthropods` | 5 | ❌ | ❌ |
| Fire Aspect | `fire_aspect` | 2 | ❌ | ❌ |
| Knockback | `knockback` | 2 | ❌ | ❌ |
| Looting | `looting` | 3 | ❌ | ❌ |
| Power | `power` | 5 | ❌ | ❌ |
| Flame | `flame` | 1 | ❌ | ❌ |
| Punch | `punch` | 2 | ❌ | ❌ |
| Infinity | `infinity` | 1 | ❌ | ❌ |
| Multishot | `multishot` | 1 | ❌ | ❌ |
| Piercing | `piercing` | 4 | ❌ | ❌ |
| Quick Charge | `quick_charge` | 3 | ❌ | ❌ |
| Impaling | `impaling` | 5 | ❌ | ❌ |
| Riptide | `riptide` | 3 | ❌ | ❌ |
| Loyalty | `loyalty` | 3 | ❌ | ❌ |
| Channeling | `channeling` | 1 | ❌ | ❌ |
| Protection | `protection` | 4 | ❌ | ❌ |
| Projectile Protection | `projectile_protection` | 4 | ❌ | ❌ |
| Fire Protection | `fire_protection` | 4 | ❌ | ❌ |
| Blast Protection | `blast_protection` | 4 | ❌ | ❌ |
| Feather Falling | `feather_falling` | 4 | ❌ | ❌ |
| Thorns | `thorns` | 3 | ❌ | ❌ |
| Frost Walker | `frost_walker` | 2 | ✅ | ❌ |
| Respiration | `respiration` | 3 | ❌ | ❌ |
| Aqua Affinity | `aqua_affinity` | 1 | ❌ | ❌ |
| Curse of Binding | `curse_of_binding` | 1 | ✅ | ✅ |
| Depth Strider | `depth_strider` | 3 | ❌ | ❌ |
| Soul Speed | `soul_speed` | 3 | ✅ | ❌ |
| Unbreaking | `unbreaking` | 3 | ❌ | ❌ |
| Mending | `mending` | 1 | ✅ | ❌ |
| Curse of Vanishing | `curse_of_vanishing` | 1 | ✅ | ✅ |

260
docs/wiki/items/equipped-item-commands.md Normal file
View File

@@ -0,0 +1,260 @@
---
title: Run Commands with Equipped Items
category: Tutorials
tags:
- experimental
- intermediate
mentions:
- Chikorita-Lover
- MedicalJewel105
- Luthorius
- TheItsNameless
---
## Introduction
A common concept for add-ons is implementing new armor sets with unique effects, just like the turtle shell and netherite armor. While items have a knockback resistance component, they don't have a component for inflicting mob effects, emitting particles, etc. under certain conditions. However, using server animations, Molang and item tags, this can easily be done!
Keep in mind that this requires modifying the player behavior, which is a common theme for many add-ons; thus, your add-on may not be compatible with others if you wish to do this.
> However some people found a way not to use player.json. They replace it with dummy entity-rider. Try experimenting yourself!
The use of Holiday Creator Features is also required to add item tags and easily equip our item in armor or off-hand slots.
## Server Animation
The first step will be to create a server animation, which is a file that runs commands or events at certain keyframes. While client animations are in the resource pack, server animations are in the behavior pack. You can read a bit more [here](/entities/timers#animation-based-timers). We can start by using the following as a template:
<CodeHeader>BP/animations/player.json</CodeHeader>
```json
{
"format_version": "1.10.0",
"animations": {
"animation.player.emerald_armor": {
"timeline": {
"0.0": []
},
"animation_length": 0.05,
"loop": true
}
}
}
```
Let's go over what's in this template and what everything does:
- `animation.player.emerald_armor` is our animation's identifier; you can change this to something else, such as `animation.player.phantom_armor`.
- `timeline` runs commands and events at given keyframes.
- `animation_length` is how long the animation lasts; we'll use 0.05 seconds, as that's the length of an in-game tick.
- `loop` is quite straight-forward; setting it to true makes the animation loop.
We can add commands to the `0.0` array in our timeline to execute, such as an `/effect` command, like such:
<CodeHeader>BP/animations/player.json#timeline</CodeHeader>
```json
{
"0.0": [
"/effect @s speed 1 0"
]
}
```
We're not limited to `/effect`, of course. If you want to use some other command, such as `/function` or `/particle`, go right ahead!
After this, we're finished in our server animation, and we'll head into the behavior file for our item for a quick addition.
## Item Behavior
To actually check if our item is equipped, we can use a Molang query that checks for item tags.
You can skip this section if:
- You want check for a vanilla item instead, such as an iron armor piece through the `minecraft:iron_tier` tag
- You want to check for the item via `q.is_item_name_any`, which checks for an item identifier in any slot
In our item's behavior, we'll have to add a tag to `components`. For example, if we wanted to add the `example:emerald_tier` tag, we would add the `tag:example:emerald_tier` component:
<CodeHeader>BP/items/my_item.json#components</CodeHeader>
```json
"tag:example:emerald_tier": {}
```
That's it, now your item has whatever tag you assigned it! You can add more tags if you want, but this is all we need for what we're doing.
## Player Behavior
Finally, we need to modify the player's behavior to run the server animation. We'll be working entirely within `description`.
First, we need to set a short name for our animation. If you have any experience with client animations, this process will be quite similar. Add `animations` to `description`, and set a short name, like such:
<CodeHeader>BP/entities/player.json#description</CodeHeader>
```json
{
"identifier": "minecraft:player",
"is_spawnable": false,
"is_summonable": false,
"is_experimental": false,
"animations": {
"emerald_armor": "animation.player.emerald_armor"
}
}
```
Now with a short name set, we can run our animation.
Add `scripts` to `description`, and set a Molang query to run. To check for the item, we can use one of the following:
- `q.is_item_name_any`, to check for a given item identifier in any slot. This example will check for `example:totem_of_retreat` in either hand:
```
q.is_item_name_any('slot.weapon.mainhand',0,'example:totem_of_retreat') || q.is_item_name_any('slot.weapon.offhand',0,'example:totem_of_retreat')
```
- `q.equipped_item_any_tag`, to check for at least one of any given tag in a given slot. This example will allow an emerald- or phantom- tier armor piece to be used:
```
q.equipped_item_any_tag('slot.armor.head','example:emerald_tier','example:phantom_tier')
```
- `q.equipped_item_all_tags`, to check for all given tags in a given slot. This example will only allow an armor piece that's both emerald- and ancient- tier:
```
q.equipped_item_all_tags('slot.armor.head','example:ancient_tier','example:emerald_tier')
```
Let's take a look at an example using `q.equipped_item_any_tag`:
<CodeHeader>BP/entities/player.json#description</CodeHeader>
```json
{
"identifier": "minecraft:player",
"is_spawnable": false,
"is_summonable": false,
"is_experimental": false,
"animations": {
"emerald_armor": "animation.player.emerald_armor"
},
"scripts": {
"animate": [
{
"emerald_armor": "q.equipped_item_any_tag('slot.armor.head','example:emerald_tier')"
}
]
}
}
```
This example will run a server animation with the `emerald_armor` short name if an emerald-tier item is equipped in the helmet slot. You can change the Molang field to match your item tag, use a different query, or add additional queries.
You can view a list of additional slot identifiers at the [Minecraft Wiki](https://minecraft.wiki/w/Slot#Bedrock_Edition).
## Conclusion
With the server animation, player behavior, and item tag all set up, your equipped item can now run commands! This technique allows for greater item customization than being restricted to item components. If you want to add more to the effect or add-on, check the next section; otherwise, congratulations, you're finished!
## Additions
### Multiple Required Items
If you want to run a command when multiple of the armor set's pieces are equipped, we can expand our Molang from before:
<CodeHeader>BP/entities/player.json#scripts</CodeHeader>
```json
"animate": [
{
"emerald_armor": "q.equipped_item_any_tag('slot.armor.head','example:emerald_tier') && q.equipped_item_any_tag('slot.armor.chest','example:emerald_tier') && q.equipped_item_any_tag('slot.armor.legs','example:emerald_tier') && q.equipped_item_any_tag('slot.armor.feet','example:emerald_tier')"
}
]
```
This example will check for emerald-tier armor in all four armor slots, and run the animation if they're all equipped.
### Further Conditions
The turtle shell doesn't always inflict Water Breathing, but instead only for 10 seconds when a player first enters water. If we want our emerald armor to only run our animation when we have lower health, we can add another query to our Molang:
<CodeHeader>BP/entities/player.json#scripts</CodeHeader>
```json
"animate": [
{
"emerald_armor": "q.equipped_item_any_tag('slot.armor.head','example:emerald_tier') && q.health <= 5"
}
]
```
This example will run the animation with 2.5 hearts or less remaining, allowing players to make a quick getaway when they're in danger.
We can also apply this to requiring multiple armor pieces, with even longer Molang:
<CodeHeader>BP/entities/player.json#scripts</CodeHeader>
```json
{
"animate": [
{
"emerald_armor": "q.equipped_item_any_tag('slot.armor.head','example:emerald_tier') && q.equipped_item_any_tag('slot.armor.chest','example:emerald_tier') && q.equipped_item_any_tag('slot.armor.legs','example:emerald_tier') && q.equipped_item_any_tag('slot.armor.feet','example:emerald_tier') && q.health <= 5"
}
]
}
```
You can view a list of documented Molang queries at [bedrock.dev](https://bedrock.dev/docs/stable/Molang#List%20of%20Entity%20Queries).
### Multiple Items with Effects
If you want to add more items with unique effects, fret not; this is easily done. You can either create a new server animation file, or add on to the file from before, like such:
<CodeHeader>BP/animations/player.json</CodeHeader>
```json
{
"format_version": "1.10.0",
"animations": {
"animation.player.emerald_armor": {
"timeline": {
"0.0": ["..."]
},
"animation_length": 0.05,
"loop": true
},
"animation.player.phantom_armor": {
"timeline": {
"0.0": ["..."]
},
"animation_length": 0.05,
"loop": true
}
}
}
```
In our player behavior, you'll have to add on to `animations` and `scripts` as well.
<CodeHeader>BP/entities/player.json#description</CodeHeader>
```json
{
"identifier": "minecraft:player",
"is_spawnable": false,
"is_summonable": false,
"is_experimental": false,
"animations": {
"emerald_armor": "animation.player.emerald_armor",
"phantom_armor": "animation.player.phantom_armor"
},
"scripts": {
"animate": [
{
"emerald_armor": "q.equipped_item_any_tag('slot.armor.head','example:emerald_tier')"
},
{
"phantom_armor": "q.equipped_item_any_tag('slot.armor.head','example:phantom_tier')"
}
]
}
}
```

10
docs/wiki/items/index.md Normal file
View File

@@ -0,0 +1,10 @@
---
title: Items
categories:
- title: General
color: blue
- title: Tutorials
color: green
- title: Documentation
color: red
---

510
docs/wiki/items/item-components.md Normal file
View File

@@ -0,0 +1,510 @@
---
title: Item Components
description: Item components are used to change how your item appears and functions in the world.
category: General
nav_order: 2
mentions:
- SmokeyStack
- QuazChick
---
:::tip FORMAT & MIN ENGINE VERSION `1.20.50`
Using the latest format version when creating custom items provides access to fresh features and improvements. The wiki aims to share up-to-date information about custom items, and currently targets format version `1.20.50`.
:::
## Applying Components
Item components are used to change how your item appears and functions in the world. They are applied in the `components` child of `minecraft:item`.
<CodeHeader>BP/items/custom_item.json</CodeHeader>
```json
{
"format_version": "1.20.50",
"minecraft:item": {
"description": {
"identifier": "wiki:custom_item",
"menu_category": {
"category": "items"
}
},
"components": {
"minecraft:icon": {
"texture": "custom_item"
}
}
}
}
```
## Allow Off Hand
Determines whether an item can be placed in the off-hand slot of the inventory.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:allow_off_hand": {
"value": true
}
```
## Block Placer
Sets the item as a Planter item component for blocks. Items with this component will place a block when used.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:block_placer":{
"block": "seeds",
"use_on": [
"dirt",
"grass"
]
}
```
## Can Destroy In Creative
Determines if an item will break blocks in Creative Mode while swinging.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:can_destroy_in_creative": {
"value": true
}
```
## Cooldown
Sets an items "Cool down" time. After using an item, it becomes unusable for the duration specified by the 'duration' setting of this component.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:cooldown":{
"category" : "attack",
"duration" : 0.2
}
```
## Damage
Determines how much extra damage an item does on attack.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:damage": {
"value": 10
}
```
## Digger
Allows a creator to determine how quickly an item can dig specific blocks.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:digger": {
"use_efficiency": true,
"destroy_speeds": [
{
"block": {
"tags": "q.any_tag('stone', 'metal')" // Note that not all blocks have tags; listing many blocks may be necessary
},
"speed": 6
}
]
}
```
## Display Name
Sets the item display name within Minecraft: Bedrock Edition. This component may also be used to pull from the localization file by referencing a key from it.
### Example
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:display_name":{
"value": "secret_weapon"
}
```
### Example Using Localization Key
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:display_name":{
"value": "item.snowball.name"
}
```
## Durability
Sets how much damage the item can take before breaking, and allows the item to be combined at an anvil, grindstone, or crafting table.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:durability":{
"damage_chance": {
"min": 10,
"max": 50
},
"max_durability": 36
}
```
## Enchantable
Determines what enchantments can be applied to the item. Not all enchantments will have an effect on all item components.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:enchantable": {
"slot": "bow",
"value": 10
}
```
### Enchantable Slots
Note: The "all" enchantable slot allows you to apply any enchantment that you want to the item, just like an enchanted book.
| Slot Name |
| ------------- |
| armor_feet |
| armor_torso |
| armor_head |
| armor_legs |
| axe |
| bow |
| cosmetic_head |
| crossbow |
| elytra |
| fishing_rod |
| flintsteel |
| hoe |
| pickaxe |
| shears |
| shield |
| shovel |
| sword |
| all |
## Entity Placer
Allows an item to place entities into the world. Additionally, in version 1.19.80 and above, the component allows the item to set the spawn type of a monster spawner.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:entity_placer":{
"entity": "minecraft:spider",
"dispense_on": ["minecraft:web"],
"use_on": ["minecraft:web"]
}
```
## Food
Sets the item as a food component, allowing it to be edible to the player.
:::tip
The `minecraft:food` must have the `minecraft:use_modifiers` component in order to function properly.
:::
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:food":{
"can_always_eat": false,
"nutrition" : 3,
"effects" : [
{
"name": "poison",
"chance": 1.0,
"duration": 5,
"amplifier": 0
}
],
"saturation_modifier": "normal",
"using_converts_to": "bowl"
}
```
## Fuel
Allows this item to be used as fuel in a furnace to 'cook' other items.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:fuel":{
"duration": 3.0
}
```
## Glint
Determines whether the item has the enchanted glint render effect on it.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:glint": false
```
## Hand Equipped
Determines if an item is rendered like a tool while in-hand.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:hand_equipped": {
"value": true
}
```
## Hover Text Color
Determines the color of the item name when hovering over it.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:hover_text_color": "green"
```
## Icon
Sets the icon item component. Determines the icon to represent the item in the UI and elsewhere.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:icon":{
"texture": "oak_slab"
}
```
## Interact Button
Is a boolean or string that determines if the interact button is shown in touch controls, and what text is displayed on the button. When set to 'true', the default 'Use Item' text will be used.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:interact_button": "Use This Custom Item" // Can be a string or a boolean value.
```
## Liquid Clipped
Determines whether an item interacts with liquid blocks on use.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:liquid_clipped": {
"value": true
}
```
## Max Stack Size
Determines how many of an item can be stacked together.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:max_stack_size": {
"value": 64
}
```
## Projectile
Compels the item to shoot, similarly to an arrow. Items with `minecraft:projectile` can be shot from dispensers or used as ammunition for items with the `minecraft:shooter` item component. Additionally, this component sets the entity that is spawned for items that also contain the `minecraft:throwable` component.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:projectile":{
"minimum_critical_power": 1.25,
"projectile_entity": "arrow"
}
```
## Record
Used by record items to play music.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:record": {
"comparator_signal": 1,
"duration": 5,
"sound_event": "ambient.tame"
}
```
### Sound Event
Listed [here](https://learn.microsoft.com/en-us/minecraft/creator/reference/content/itemreference/examples/itemcomponents/minecraft_record?view=minecraft-bedrock-stable) are the available sounds
## Repairable
Defines the items that can be used to repair a defined item, and the amount of durability each item restores upon repair. Each entry needs to define a list of strings for 'items' that can be used for the repair and an optional 'repair_amount' for how much durability is repaired.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:repairable":{
"on_repaired": "minecraft:celebrate",
"repair_items": ["anvil"]
}
```
## Shooter
Compels an item to shoot projectiles, similarly to a bow or crossbow. Must have the `minecraft:use_modifiers` component in order to function properly.
:::tip
Ammunition used by `minecraft:shooter` must have the `minecraft:projectile` component in order to function properly.
:::
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:shooter": {
"ammunition": [
{
"item": "custom_projectile",
"use_offhand": true,
"search_inventory": true,
"use_in_creative": true
}
],
"max_draw_duration": 1.0,
"scale_power_by_draw_duration": true,
"charge_on_draw": false
}
```
## Should Despawn
Determines if an item should despawn while floating in the world.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:should_despawn": {
"value": true
}
```
## Stacked By Data
Determines if the same item with different aux values can stack. Additionally, this component defines whether the item actors can merge while floating in the world.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:stacked_by_data": {
"value": true
}
```
## Tags
Determines which tags are included on a given item.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:tags": {
"tags": [
"custom_tag"
]
}
```
## Throwable
Sets the throwable item component.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:throwable":{
"do_swing_animation" : false,
"launch_power_scale" : 1.0,
"max_draw_duration" : 0.0,
"max_launch_power" : 1.0,
"min_draw_duration" : 0.0,
"scale_power_by_draw_duration" : false
}
```
## Use Animation
Determines which animation plays when using an item.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:use_animation": "eat"
```
## Use Modifiers
Determines how long an item takes to use in combination with components such as Shooter, Throwable, or Food.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:use_modifiers": {
"use_duration": 1.6,
"movement_modifier": 0.35
}
```
## Wearable
Sets the wearable item component.
<CodeHeader>minecraft:item > components</CodeHeader>
```json
"minecraft:wearable":{
"dispensable" : true,
"slot": "slot.chest"
}
```
### Slots
| Slot Name |
| -------------------- |
| slot.weapon.mainhand |
| slot.weapon.offhand |
| slot.armor.head |
| slot.armor.chest |
| slot.armor.legs |
| slot.armor.feet |
| slot.hotbar |
| slot.inventory |
| slot.enderchest |
| slot.saddle |
| slot.armor |
| slot.chest |
| slot.equippable |

138
docs/wiki/items/item-identifiers.md Normal file
View File

@@ -0,0 +1,138 @@
---
title: Vanilla Item Identifiers
category: Documentation
tags:
- deprecated
mentions:
- TheDoctor15
- Medicaljewel105
- Luthorius
- epxzzy
- SmokeyStack
---
:::danger
This method no longer works after 1.18.30.
:::
An `identifier` is a required parameter that sits inside the description of the item's behaviour file.
It accepts Vanilla Minecraft names, like so, `<namespace>:<vanilla item>`, which will apply certain hardcoded item behaviours, depending on the identifier used.
<CodeHeader>BP/items/custom_item.json#minecraft:item</CodeHeader>
```json
"description": {
"identifier": "wiki:totem_of_undying",
"category": "items"
}
```
:::warning
Not every Vanilla Identifier and their behaviours are documented. The following list may be missing important points about the known Identifiers that do affect items.
Consider experimenting with them.
:::
## Known Identifier Effects
The namespace is allowed to be changed, learn more about namespaces [here](/concepts/namespaces).
### namespace:banner
- The item icon and model will be changed to that of the Vanilla Banner.
---
### namespace:bow
- Adds a small increasing zoom on use, for the zoom to work it requires the item to be usable.
---
### namespace:crossbow
- The item will be rotated horizontally on your arm.
---
### namespace:diamond
- Is accepted as a valid item to change the effect given off by a Beacon.
---
### namespace:emerald
- Is accepted as a valid item to change the effect given off by a Beacon.
---
### namespace:filled_map
- Will add the holding map animation.
- Can be put in a cartography table.
---
### namespace:gold_ingot
- Is accepted as a valid item to change the effect given off by a Beacon.
---
### namespace:iron_ingot
- Is accepted as a valid item to change the effect given off by a Beacon.
---
### namespace:lapis_lazuli
- Makes the Item usable with Enchantment Tables, to enchant your items in place of Lapis Lazuli.
---
### namespace:lead
- Will behave like a Lead.
---
### namespace:map
- Will use the holding map animation.
---
### namespace:netherite_ingot
- Is accepted in custom Smithing Recipes as the secondary item.
- Is accepted as a valid item to change the effect given off by a Beacon.
---
### namespace:shield
- The item icon will be permanently changed to that of the Vanilla Shield.
- Adds the shield animation and behavior.
---
### namespace:spyglass
- Makes it zoom-able like a spyglass, for the zoom to work it requires the item to be usable.
---
### namespace:skull
- The item icon will be changed to that of the Vanilla Skull.
- The item will be able to put on a armorstand and a player, the model and textures of the skull will be applied only then.
---
### namespace:totem_of_undying
- Will behave like a Totem of Undying.
---

125
docs/wiki/items/item-tags.md Normal file
View File

@@ -0,0 +1,125 @@
---
title: Item Tags
category: General
nav_order: 3
mentions:
- Xterionix
- SmokeyStack
---
Item tags can be used to ensure that a item meets certain conditions.
## Applying Tags
### From 1.20.50 and onwards
<CodeHeader></CodeHeader>
```json
{
"format_version": "1.20.50",
"minecraft:item": {
"description": {
"identifier": "example:my_item"
},
"components": {
"minecraft:tags": {
"tags": [
"example:my_tag"
]
}
}
}
}
```
### Before 1.20.50
<CodeHeader></CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "example:my_item"
},
"components": {
"tag:example:my_tag": {}
}
}
}
```
## Testing for Tags
Tags can be queried with:
- `q.all_tags`
- `q.any_tag`
- `q.equipped_item_all_tags`
- `q.equipped_item_any_tag`
## Lists of Vanilla Item Tags
Vanilla tags can be applied to custom items, and some vanilla items are tagged internally.
| Tag | Items |
|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| minecraft:arrow | minecraft:arrow |
| minecraft:banner | minecraft:banner |
| minecraft:boat | minecraft:birch_boat, minecraft:bamboo_raft, minecraft:cherry_chest_boat, minecraft:mangrove_boat, minecraft:bamboo_chest_raft, minecraft:jungle_chest_boat, minecraft:oak_boat, minecraft:oak_chest_boat, minecraft:dark_oak_chest_boat, minecraft:cherry_boat, minecraft:mangrove_chest_boat, minecraft:acacia_boat, minecraft:acacia_chest_boat, minecraft:jungle_boat, minecraft:spruce_chest_boat, minecraft:dark_oak_boat, minecraft:boat, minecraft:spruce_boat, minecraft:birch_chest_boat, minecraft:chest_boat |
| minecraft:boats | minecraft:birch_boat, minecraft:bamboo_raft, minecraft:cherry_chest_boat, minecraft:mangrove_boat, minecraft:bamboo_chest_raft, minecraft:jungle_chest_boat, minecraft:oak_boat, minecraft:oak_chest_boat, minecraft:dark_oak_chest_boat, minecraft:cherry_boat, minecraft:mangrove_chest_boat, minecraft:acacia_boat, minecraft:acacia_chest_boat, minecraft:jungle_boat, minecraft:spruce_chest_boat, minecraft:dark_oak_boat, minecraft:boat, minecraft:spruce_boat, minecraft:birch_chest_boat, minecraft:chest_boat |
| minecraft:bookshelf_books | minecraft:writable_book, minecraft:book, minecraft:enchanted_book |
| minecraft:chainmail_tier | minecraft:chainmail_leggings, minecraft:chainmail_helmet, minecraft:chainmail_chestplate, minecraft:chainmail_boots |
| minecraft:coals | minecraft:coal, minecraft:charcoal |
| minecraft:crimson_stems | minecraft:stripped_crimson_stem, minecraft:stripped_crimson_hyphae, minecraft:crimson_stem, minecraft:crimson_hyphae |
| minecraft:decorated_pot_sherds | minecraft:friend_pottery_sherd, minecraft:archer_pottery_sherd, minecraft:burn_pottery_sherd, minecraft:heart_pottery_sherd, minecraft:arms_up_pottery_sherd, minecraft:brick, minecraft:danger_pottery_sherd, minecraft:heartbreak_pottery_sherd, minecraft:shelter_pottery_sherd, minecraft:explorer_pottery_sherd, minecraft:prize_pottery_sherd, minecraft:skull_pottery_sherd, minecraft:sheaf_pottery_sherd, minecraft:angler_pottery_sherd, minecraft:blade_pottery_sherd, minecraft:brewer_pottery_sherd, minecraft:howl_pottery_sherd, minecraft:miner_pottery_sherd, minecraft:mourner_pottery_sherd, minecraft:plenty_pottery_sherd, minecraft:snort_pottery_sherd |
| minecraft:diamond_tier | minecraft:diamond_chestplate, minecraft:diamond_boots, minecraft:diamond_helmet, minecraft:diamond_pickaxe, minecraft:diamond_leggings, minecraft:diamond_sword, minecraft:diamond_axe, minecraft:diamond_shovel, minecraft:diamond_hoe |
| minecraft:digger | minecraft:wooden_pickaxe, minecraft:golden_pickaxe, minecraft:netherite_hoe, minecraft:wooden_shovel, minecraft:wooden_hoe, minecraft:golden_axe, minecraft:iron_axe, minecraft:netherite_pickaxe, minecraft:iron_hoe, minecraft:wooden_axe, minecraft:stone_hoe, minecraft:stone_shovel, minecraft:stone_axe, minecraft:diamond_pickaxe, minecraft:netherite_axe, minecraft:diamond_axe, minecraft:stone_pickaxe, minecraft:iron_pickaxe, minecraft:iron_shovel, minecraft:golden_shovel, minecraft:diamond_shovel, minecraft:netherite_shovel, minecraft:golden_hoe, minecraft:diamond_hoe |
| minecraft:door | minecraft:wooden_door, minecraft:iron_door, minecraft:warped_door, minecraft:dark_oak_door, minecraft:crimson_door, minecraft:acacia_door, minecraft:jungle_door, minecraft:spruce_door, minecraft:birch_door, minecraft:mangrove_door, minecraft:cherry_door, minecraft:bamboo_door |
| minecraft:golden_tier | minecraft:golden_pickaxe, minecraft:golden_axe, minecraft:golden_chestplate, minecraft:golden_leggings, minecraft:golden_sword, minecraft:golden_helmet, minecraft:golden_boots, minecraft:golden_shovel, minecraft:golden_hoe |
| minecraft:hanging_actor | minecraft:painting |
| minecraft:hanging_sign | minecraft:warped_hanging_sign, minecraft:crimson_hanging_sign, minecraft:acacia_hanging_sign, minecraft:bamboo_hanging_sign, minecraft:dark_oak_hanging_sign, minecraft:jungle_hanging_sign, minecraft:cherry_hanging_sign, minecraft:oak_hanging_sign, minecraft:birch_hanging_sign, minecraft:mangrove_hanging_sign, minecraft:spruce_hanging_sign |
| minecraft:horse_armor | minecraft:diamond_horse_armor, minecraft:iron_horse_armor, minecraft:leather_horse_armor, minecraft:golden_horse_armor |
| minecraft:iron_tier | minecraft:iron_boots, minecraft:iron_axe, minecraft:iron_hoe, minecraft:iron_leggings, minecraft:iron_chestplate, minecraft:iron_sword, minecraft:iron_helmet, minecraft:iron_pickaxe, minecraft:iron_shovel |
| minecraft:is_armor | minecraft:iron_boots, minecraft:turtle_helmet, minecraft:chainmail_leggings, minecraft:diamond_chestplate, minecraft:diamond_boots, minecraft:leather_boots, minecraft:golden_chestplate, minecraft:netherite_helmet, minecraft:golden_leggings, minecraft:iron_leggings, minecraft:diamond_helmet, minecraft:iron_chestplate, minecraft:chainmail_helmet, minecraft:leather_helmet, minecraft:chainmail_chestplate, minecraft:elytra, minecraft:netherite_chestplate, minecraft:netherite_leggings, minecraft:netherite_boots, minecraft:leather_leggings, minecraft:chainmail_boots, minecraft:iron_helmet, minecraft:golden_helmet, minecraft:leather_chestplate, minecraft:diamond_leggings, minecraft:golden_boots |
| minecraft:is_axe | minecraft:golden_axe, minecraft:iron_axe, minecraft:wooden_axe, minecraft:stone_axe minecraft:netherite_axe, minecraft:diamond_axe |
| minecraft:is_cooked | minecraft:cooked_porkchop, minecraft:rabbit_stew, minecraft:cooked_salmon, minecraft:cooked_cod, minecraft:cooked_chicken, minecraft:cooked_beef, minecraft:cooked_mutton, minecraft:cooked_rabbit |
| minecraft:is_fish | minecraft:salmon, minecraft:cooked_salmon, minecraft:pufferfish, minecraft:cooked_cod, minecraft:tropical_fish, minecraft:cod |
| minecraft:is_food | minecraft:cookie, minecraft:sweet_berries, minecraft:cooked_porkchop, minecraft:carrot, minecraft:enchanted_golden_apple, minecraft:golden_carrot, minecraft:golden_apple, minecraft:beetroot_soup, minecraft:rabbit_stew, minecraft:chicken, minecraft:porkchop, minecraft:beef, minecraft:bread, minecraft:beetroot, minecraft:potato, minecraft:dried_kelp, minecraft:cooked_chicken, minecraft:apple, minecraft:melon_slice, minecraft:mutton, minecraft:rabbit, minecraft:rotten_flesh, minecraft:cooked_beef, minecraft:cooked_mutton, minecraft:cooked_rabbit, minecraft:mushroom_stew, minecraft:baked_potato, minecraft:pumpkin_pie |
| minecraft:is_hoe | minecraft:netherite_hoe, minecraft:wooden_hoe, minecraft:iron_hoe, minecraft:stone_hoe, minecraft:golden_hoe, minecraft:diamond_hoe |
| minecraft:is_meat | minecraft:cooked_porkchop, minecraft:rabbit_stew, minecraft:chicken, minecraft:porkchop, minecraft:beef, minecraft:cooked_chicken, minecraft:mutton, minecraft:rabbit, minecraft:rotten_flesh, minecraft:cooked_beef, minecraft:cooked_mutton, minecraft:cooked_rabbit |
| minecraft:is_minecart | minecraft:tnt_minecart, minecraft:command_block_minecart, minecraft:chest_minecart, minecraft:minecart, minecraft:hopper_minecart |
| minecraft:is_pickaxe | minecraft:wooden_pickaxe, minecraft:golden_pickaxe, minecraft:netherite_pickaxe, minecraft:diamond_pickaxe, minecraft:stone_pickaxe, minecraft:iron_pickaxe |
| minecraft:is_shovel | minecraft:wooden_shovel, minecraft:stone_shovel, minecraft:iron_shovel, minecraft:golden_shovel, minecraft:diamond_shovel, minecraft:netherite_shovel |
| minecraft:is_sword | minecraft:netherite_sword, minecraft:stone_sword, minecraft:iron_sword, minecraft:golden_sword, minecraft:wooden_sword, minecraft:diamond_sword |
| minecraft:is_tool | minecraft:wooden_pickaxe, minecraft:golden_pickaxe, minecraft:netherite_sword, minecraft:netherite_hoe, minecraft:wooden_shovel, minecraft:wooden_hoe, minecraft:stone_sword, minecraft:golden_axe, minecraft:iron_axe, minecraft:netherite_pickaxe, minecraft:iron_hoe, minecraft:wooden_axe, minecraft:iron_sword, minecraft:stone_hoe, minecraft:stone_shovel, minecraft:golden_sword, minecraft:stone_axe, minecraft:diamond_pickaxe, minecraft:netherite_axe, minecraft:wooden_sword, minecraft:diamond_sword, minecraft:diamond_axe, minecraft:stone_pickaxe, minecraft:iron_pickaxe, minecraft:iron_shovel, minecraft:golden_shovel, minecraft:diamond_shovel, minecraft:netherite_shovel, minecraft:golden_hoe, minecraft:diamond_hoe |
| minecraft:is_trident | minecraft:trident |
| minecraft:leather_tier | minecraft:leather_boots, minecraft:leather_helmet, minecraft:leather_leggings, minecraft:leather_chestplate |
| minecraft:lectern_books | minecraft:writable_book |
| minecraft:logs | minecraft:dark_oak_log, minecraft:warped_stem, minecraft:stripped_warped_stem, minecraft:mangrove_log, minecraft:jungle_log, minecraft:birch_log, minecraft:stripped_crimson_stem, minecraft:stripped_jungle_log, minecraft:stripped_crimson_hyphae, minecraft:oak_log, minecraft:wood, minecraft:warped_hyphae, minecraft:stripped_oak_log, minecraft:stripped_cherry_wood, minecraft:stripped_mangrove_wood, minecraft:stripped_cherry_log, minecraft:stripped_warped_hyphae, minecraft:crimson_stem, minecraft:stripped_birch_log, minecraft:crimson_hyphae, minecraft:stripped_dark_oak_log, minecraft:stripped_acacia_log, minecraft:stripped_mangrove_log, minecraft:stripped_spruce_log, minecraft:spruce_log, minecraft:acacia_log, minecraft:mangrove_wood, minecraft:cherry_log, minecraft:cherry_wood, minecraft:log, minecraft:log2 |
| minecraft:logs_that_burn | minecraft:dark_oak_log, minecraft:mangrove_log, minecraft:jungle_log, minecraft:birch_log, minecraft:stripped_jungle_log, minecraft:oak_log, minecraft:wood, minecraft:stripped_oak_log, minecraft:stripped_cherry_wood, minecraft:stripped_mangrove_wood, minecraft:stripped_cherry_log, minecraft:stripped_birch_log, minecraft:stripped_dark_oak_log, minecraft:stripped_acacia_log, minecraft:stripped_mangrove_log, minecraft:stripped_spruce_log, minecraft:spruce_log, minecraft:acacia_log, minecraft:mangrove_wood, minecraft:cherry_log, minecraft:cherry_wood, minecraft:log, minecraft:log2 |
| minecraft:mangrove_logs | minecraft:mangrove_log, minecraft:stripped_mangrove_wood, minecraft:stripped_mangrove_log, minecraft:mangrove_wood |
| minecraft:music_disc | minecraft:music_disc_strad, minecraft:music_disc_11, minecraft:music_disc_mellohi, minecraft:music_disc_otherside, minecraft:music_disc_wait, minecraft:music_disc_relic, minecraft:music_disc_5, minecraft:music_disc_stal, minecraft:music_disc_pigstep, minecraft:music_disc_blocks, minecraft:music_disc_cat, minecraft:music_disc_far, minecraft:music_disc_13, minecraft:music_disc_chirp, minecraft:music_disc_mall, minecraft:music_disc_ward |
| minecraft:netherite_tier | minecraft:netherite_sword, minecraft:netherite_hoe, minecraft:netherite_pickaxe, minecraft:netherite_helmet, minecraft:netherite_chestplate, minecraft:netherite_leggings, minecraft:netherite_boots, minecraft:netherite_axe, minecraft:netherite_shovel |
| minecraft:planks | minecraft:dark_oak_planks, minecraft:spruce_planks, minecraft:oak_planks, minecraft:birch_planks, minecraft:acacia_planks, minecraft:bamboo_planks, minecraft:jungle_planks, minecraft:warped_planks, minecraft:mangrove_planks, minecraft:cherry_planks, minecraft:crimson_planks, minecraft:planks |
| minecraft:sand | minecraft:sand |
| minecraft:sign | minecraft:oak_sign, minecraft:jungle_sign, minecraft:warped_hanging_sign, minecraft:cherry_sign, minecraft:birch_sign, minecraft:crimson_hanging_sign, minecraft:acacia_hanging_sign, minecraft:bamboo_hanging_sign, minecraft:dark_oak_hanging_sign, minecraft:acacia_sign, minecraft:jungle_hanging_sign, minecraft:spruce_sign, minecraft:dark_oak_sign, minecraft:cherry_hanging_sign, minecraft:oak_hanging_sign, minecraft:mangrove_sign, minecraft:birch_hanging_sign, minecraft:mangrove_hanging_sign, minecraft:bamboo_sign, minecraft:crimson_sign, minecraft:warped_sign, minecraft:spruce_hanging_sign |
| minecraft:soul_fire_base_blocks | minecraft:soul_sand, minecraft:soul_soil |
| minecraft:spawn_egg | minecraft:blaze_spawn_egg, minecraft:piglin_brute_spawn_egg, minecraft:ghast_spawn_egg, minecraft:bee_spawn_egg, minecraft:hoglin_spawn_egg, minecraft:wolf_spawn_egg, minecraft:rabbit_spawn_egg, minecraft:drowned_spawn_egg, minecraft:ender_dragon_spawn_egg, minecraft:glow_squid_spawn_egg, minecraft:fox_spawn_egg, minecraft:pig_spawn_egg, minecraft:piglin_spawn_egg, minecraft:ravager_spawn_egg, minecraft:endermite_spawn_egg, minecraft:frog_spawn_egg, minecraft:elder_guardian_spawn_egg, minecraft:iron_golem_spawn_egg, minecraft:axolotl_spawn_egg, minecraft:panda_spawn_egg, minecraft:spider_spawn_egg, minecraft:strider_spawn_egg, minecraft:chicken_spawn_egg, minecraft:cod_spawn_egg, minecraft:shulker_spawn_egg, minecraft:pillager_spawn_egg, minecraft:slime_spawn_egg, minecraft:salmon_spawn_egg, minecraft:creeper_spawn_egg, minecraft:polar_bear_spawn_egg, minecraft:llama_spawn_egg, minecraft:goat_spawn_egg, minecraft:trader_llama_spawn_egg, minecraft:wither_spawn_egg, minecraft:parrot_spawn_egg, minecraft:horse_spawn_egg, minecraft:sniffer_spawn_egg, minecraft:husk_spawn_egg, minecraft:bat_spawn_egg, minecraft:turtle_spawn_egg, minecraft:sheep_spawn_egg, minecraft:tropical_fish_spawn_egg, minecraft:evoker_spawn_egg, minecraft:vex_spawn_egg, minecraft:skeleton_horse_spawn_egg, minecraft:tadpole_spawn_egg, minecraft:cow_spawn_egg, minecraft:villager_spawn_egg, minecraft:cat_spawn_egg, minecraft:warden_spawn_egg, minecraft:skeleton_spawn_egg, minecraft:cave_spider_spawn_egg, minecraft:magma_cube_spawn_egg, minecraft:zombie_pigman_spawn_egg, minecraft:pufferfish_spawn_egg, minecraft:wandering_trader_spawn_egg, minecraft:dolphin_spawn_egg, minecraft:spawn_egg, minecraft:ocelot_spawn_egg, minecraft:mooshroom_spawn_egg, minecraft:donkey_spawn_egg, minecraft:mule_spawn_egg, minecraft:zombie_horse_spawn_egg, minecraft:enderman_spawn_egg, minecraft:silverfish_spawn_egg, minecraft:wither_skeleton_spawn_egg, minecraft:stray_spawn_egg, minecraft:zombie_spawn_egg, minecraft:squid_spawn_egg, minecraft:witch_spawn_egg, minecraft:guardian_spawn_egg, minecraft:zoglin_spawn_egg, minecraft:allay_spawn_egg, minecraft:camel_spawn_egg, minecraft:vindicator_spawn_egg, minecraft:zombie_villager_spawn_egg, minecraft:phantom_spawn_egg, minecraft:snow_golem_spawn_egg |
| minecraft:stone_bricks | minecraft:stonebrick |
| minecraft:stone_crafting_materials | minecraft:cobbled_deepslate, minecraft:cobblestone, minecraft:blackstone |
| minecraft:stone_tier | minecraft:stone_sword, minecraft:stone_hoe, minecraft:stone_shovel, minecraft:stone_axe, minecraft:stone_pickaxe |
| minecraft:stone_tool_materials | minecraft:cobbled_deepslate, minecraft:cobblestone, minecraft:blackstone |
| minecraft:transform_materials | minecraft:netherite_ingot |
| minecraft:transform_templates | minecraft:netherite_upgrade_smithing_template |
| minecraft:transformable_items | minecraft:diamond_chestplate, minecraft:diamond_boots, minecraft:diamond_helmet, minecraft:diamond_pickaxe, minecraft:diamond_leggings, minecraft:golden_boots, minecraft:diamond_sword, minecraft:diamond_axe, minecraft:diamond_shovel, minecraft:diamond_hoe |
| minecraft:transformable_items | minecraft:gold_ingot, minecraft:redstone, minecraft:diamond, minecraft:netherite_ingot, minecraft:copper_ingot, minecraft:lapis_lazuli, minecraft:emerald, minecraft:iron_ingot, minecraft:amethyst_shard, minecraft:quartz |
| minecraft:trim_templates | minecraft:eye_armor_trim_smithing_template, minecraft:raiser_armor_trim_smithing_template, minecraft:sentry_armor_trim_smithing_template, minecraft:host_armor_trim_smithing_template, minecraft:snout_armor_trim_smithing_template, minecraft:spire_armor_trim_smithing_template, minecraft:wayfinder_armor_trim_smithing_template, minecraft:ward_armor_trim_smithing_template, minecraft:vex_armor_trim_smithing_template, minecraft:wild_armor_trim_smithing_template, minecraft:coast_armor_trim_smithing_template, minecraft:dune_armor_trim_smithing_template, minecraft:shaper_armor_trim_smithing_template, minecraft:silence_armor_trim_smithing_template, minecraft:tide_armor_trim_smithing_template, minecraft:rib_armor_trim_smithing_template |
| minecraft:trimmable_armors | minecraft:iron_boots, minecraft:turtle_helmet, minecraft:chainmail_leggings, minecraft:diamond_chestplate, minecraft:diamond_boots, minecraft:leather_boots, minecraft:golden_chestplate, minecraft:netherite_helmet, minecraft:golden_leggings, minecraft:iron_leggings, minecraft:diamond_helmet, minecraft:iron_chestplate, minecraft:chainmail_helmet, minecraft:leather_helmet, minecraft:chainmail_chestplate, minecraft:netherite_chestplate, minecraft:netherite_leggings, minecraft:netherite_boots, minecraft:leather_leggings, minecraft:chainmail_boots, minecraft:iron_helmet, minecraft:golden_helmet, minecraft:leather_chestplate, minecraft:diamond_leggings, minecraft:golden_boots |
| minecraft:vibration_damper | minecraft:white_wool, minecraft:green_wool, minecraft:magenta_wool, minecraft:gray_wool, minecraft:orange_wool, minecraft:orange_carpet, minecraft:gray_carpet, minecraft:red_carpet, minecraft:cyan_carpet, minecraft:light_gray_wool, minecraft:red_wool, minecraft:pink_wool, minecraft:brown_wool, minecraft:purple_carpet, minecraft:light_blue_carpet, minecraft:white_carpet, minecraft:black_wool, minecraft:wool, minecraft:light_blue_wool, minecraft:light_gray_carpet, minecraft:yellow_wool, minecraft:lime_wool, minecraft:cyan_wool, minecraft:black_carpet, minecraft:blue_wool, minecraft:purple_wool, minecraft:pink_carpet, minecraft:brown_carpet, minecraft:green_carpet, minecraft:yellow_carpet, minecraft:lime_carpet, minecraft:blue_carpet, minecraft:magenta_carpet, minecraft:carpet |
| minecraft:warped_stems | minecraft:warped_stem, minecraft:stripped_warped_stem, minecraft:warped_hyphae, minecraft:stripped_warped_hyphae |
| minecraft:wooden_slabs | minecraft:warped_slab, minecraft:wooden_slab, minecraft:crimson_slab, minecraft:bamboo_slab, minecraft:mangrove_slab, minecraft:cherry_slab |
| minecraft:wooden_tier | minecraft:wooden_pickaxe, minecraft:wooden_shovel, minecraft:wooden_hoe, minecraft:wooden_axe, minecraft:wooden_sword |
| minecraft:wool | minecraft:white_wool, minecraft:green_wool, minecraft:magenta_wool, minecraft:gray_wool, minecraft:orange_wool, minecraft:light_gray_wool, minecraft:red_wool, minecraft:pink_wool, minecraft:brown_wool, minecraft:black_wool, minecraft:wool, minecraft:light_blue_wool, minecraft:yellow_wool, minecraft:lime_wool, minecraft:cyan_wool, minecraft:blue_wool, minecraft:purple_wool |

156
docs/wiki/items/items-intro.md Normal file
View File

@@ -0,0 +1,156 @@
---
title: Intro to Items
description: A "Hello world" guide in making items. Learn the item format and how to create basic custom items.
category: General
nav_order: 1
tags:
- guide
- beginner
mentions:
- SirLich
- solvedDev
- Joelant05
- yanasakana
- destruc7ion
- aexer0e
- stirante
- ChibiMango
- MedicalJewel105
- Sprunkles317
- mark-wiemer
- TheItsNameless
- s1050613
- SmokeyStack
---
Minecraft Bedrock allows us to add custom items into our world with various vanilla-like properties
This tutorial will cover how to create basic items for the stable version of Minecraft.
## Registering Items
Item definitions are structured similarly to entities: they contain a description and a list of components that defines the item's behavior.
Below is the **minimum** behavior-side code to get a custom item into the creative inventory.
<CodeHeader>BP/items/custom_item.json</CodeHeader>
```json
{
"format_version": "1.20.50",
"minecraft:item": {
"description": {
"identifier": "wiki:custom_item",
"menu_category": {
"category": "construction"
}
},
"components": {} // Must be here, even if empty!
}
}
```
### Item Description
- Defines the item's identifier - a unique ID in the format of `namespace:identifier`.
- Configures which `menu_category` the item is placed into.
- Also takes the optional parameters `group` and `is_hidden_in_commands`.
## Adding Components
Right now, our custom item is using the default component values (which can be found [here](/items/item-components)).
Let's configure our own functionality!
<CodeHeader>BP/items/custom_item.json</CodeHeader>
```json
{
"format_version": "1.20.50",
"minecraft:item": {
"description": {
"identifier": "wiki:custom_item",
"menu_category": {
"category": "construction"
}
},
"components": {
"minecraft:damage": {
"value": 10
},
"minecraft:durability":{
"max_durability": 36
},
"minecraft:hand_equipped": {
"value": true
}
}
}
}
```
Browse more item components [here](/items/item-components)!
## Applying Textures
We need to create a texture shortname to link it to an image in `RP/textures/item_texture.json`.
<CodeHeader>RP/textures/item_texture.json</CodeHeader>
```json
{
"resource_pack_name": "wiki",
"texture_name": "atlas.items",
"texture_data": {
"custom_item": {
"textures": "textures/items/custom_item"
}
}
}
```
In our item file, we will add the `minecraft:icon` component to apply the texture.
<CodeHeader>BP/items/custom_item.json</CodeHeader>
```json
{
"format_version": "1.20.50",
"minecraft:item": {
"description": {
"identifier": "wiki:custom_item",
"menu_category": {
"category": "construction"
}
},
"components": {
"minecraft:icon": {
"texture": "custom_item"
}
}
}
}
```
## Defining Names
Finally, we will give our item a name. Additionally, you can use the [Display Name](/items/item-components#display_name) component.
<CodeHeader>RP/texts/en_US.lang</CodeHeader>
```c
tile.wiki:custom_item.name=Custom Item
```
## Result
In this page, you've learnt about the following:
<Checklist>
- [x] Basic features of items
- [x] How to apply a texture
- [x] How to link textures using shortnames in `item_textures.json`
- [x] How to define names in the language file
</Checklist>

1422
docs/wiki/items/numerical-item-ids.md Normal file
View File

File diff suppressed because it is too large Load Diff

176
docs/wiki/items/spawning-items.md Normal file
View File

@@ -0,0 +1,176 @@
---
title: Spawning Items
category: Tutorials
tags:
- intermediate
mentions:
- SirLich
- Joelant05
- Dreamedc2015
- yanasakana
- MedicalJewel105
- aexer0e
- Xterionix
---
It is fairly common to want to spawn an item in the world, as if dropped. This page will walk through how to accomplish this through various methods, including Entity Deaths, Interactions, and an all-purpose method.
## /loot
The simplest method of spawning items to date is by using /loot. Formatted as such:
```
/loot spawn ~ ~ ~ loot "entities/cow"
```
<CodeHeader>BP/loot_tables/entities/cow.json</CodeHeader>
```json
"minecraft:loot": {
"table": "loot_tables/entities/cow.json"
}
```
## Entity Deaths
Another simple method of spawning items - and generally the most common one - is dropping items upon an entity's death. This is done by adding the `minecraft:loot` component to the entity and linking it to the respective loot table (`forium` in the following example) containing items you wish to be dropped.
<CodeHeader>BP/entities/my_entity.json#components</CodeHeader>
```json
"minecraft:loot": {
"table": "loot_tables/entities/forium.json"
}
```
## Dummy Entity Deaths
We can use `minecraft:loot` on a [dummy entity](/entities/dummy-entities) that dies when we spawn it to create a `drop_entity`. This entity can be summoned like `/summon wiki:drop_entity` to spawn the items. This is useful for scenarios where death particles or sounds are not an issue.
Behaviors:
<CodeHeader>BP/entities/my_entity.json</CodeHeader>
```json
{
"format_version": "1.16.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:drop_entity",
"is_spawnable": true,
"is_summonable": true,
"is_experimental": false
},
"components": {
// Causes the entity to die when spawned
"minecraft:health": {
"value": 0
},
"minecraft:loot": {
"table": "loot_tables/entities/some_loot.json"
}
}
}
}
```
## Interactions
Here is an example of an entity called "box" which will drop its contents upon interaction. The table in `spawn_items` is linked to the loot table with the items desired to be dropped. In this particular case, the event `break_box` is also called when the entity is interacted with, adding a component group that removes the box.
Note that if the entity is not removed upon interaction, it can be interacted with again and will spawn the items. If the entity should persist after the interaction, the `cooldown` parameter may be added to the entity to prevent interaction for a specified amount of time. Alternatively, an event may be called to remove the component group containing this `minecraft:interact` component.
<CodeHeader>BP/entities/my_entity.json#components</CodeHeader>
```json
"minecraft:interact": {
"interactions": [
{
"on_interact": {
"filters": {
"test": "is_family",
"subject": "other",
"value": "player"
},
"event": "break_box",
"target": "self"
},
"swing": true,
"spawn_items": {
"table": "loot_tables/entities/box.json"
}
}
]
}
```
## All-Purpose Method
This is a method that can be used for virtually any scenario: entity deaths, animation-based interactions, general item drops. This method was created in particular for dropping items without any death animation, sound, or particles.
Several parts are required to set up the item dropping: a new entity with behavior, a corresponding animation controller, the resources for an invisible entity (refer to Dummy Entities tutorial), and a loot table. To spawn the items after it is set up, the entity is spawned where the items are to be dropped. If multiple items are desired, component groups with spawn events may be set up for each item.
### Behavior
The items are spawned using the `minecraft:behavior.drop_item_for` component in conjunction with the `minecraft:navigation.walk` component, the latter being required for the former to work. Note that the `time_of_day_range` parameter in the following is not initialized to how it is defined below despite the documentation listing it as such, and this is necessary for proper function. The parameter `max_dist` must be increased to an appropriate value if the items are desired to be dropped when the player is very far away.
This behavior appears to push the mob back when the items are dropped. Thus it is essential to summon the entity slightly above the ground (or teleport it up in the following animation controller) to avoid the items spawning a few blocks away from the spawn location. Decreasing the size of the collision box may also help.
<CodeHeader>BP/entities/my_entity.json#components</CodeHeader>
```json
"minecraft:navigation.walk": {},
"minecraft:behavior.drop_item_for": {
"priority": 1,
"max_dist": 16,
"loot_table": "loot_tables/entities/forium.json",
"time_of_day_range": [0.0, 1.0]
}
```
### Animation Controller
**The following animation controller must be linked to the entity** to remove it upon summoning. Alternatively, an animation with a timeline can be used. If you are unsure how to do this, refer to the Entity Commands tutorial.
Teleporting the entity into the void causes no death animation, sound, or particles. Two transitions are used to ensure it is not killed in the same tick it spawns.
<CodeHeader>BP/animation_controllers/my_entity.ac.json</CodeHeader>
```json
{
"format_version": "1.10.0",
"animation_controllers": {
"controller.animation.drop_items.die": {
"initial_state": "spawn",
"states": {
"spawn": {
"transitions": [
{
"delay": "1"
}
]
},
"delay": {
"transitions": [
{
"die": "1"
}
]
},
"die": {
"on_entry": ["/tp @s ~ -200 ~"]
}
}
}
}
}
```
## Structure Method
There is also one interesting method of spawning items - via structure.
You can fill a structure with `structure_void` (so air doesn't replace blocks when structure loaded) and drop an item into it.
This method allows us to keep item data (such as durability).
Then you can load this structure whenever and wherever you want.
![](/assets/images/items/spawning-items/structure-method.png)

402
docs/wiki/items/spear.md Normal file
View File

@@ -0,0 +1,402 @@
---
title: Custom Spear
category: Tutorials
tags:
- scripting
mentions:
- XxPoggyisLitxX
- SirLich
- TheItsNamless
- ThomasOrs
- kumja1
hidden: true
---
::: tip
It's highly recommended that you have a basic understanding of JavaScript and Script-API.
:::
::: warning
It's highly recommended that you have made the basic textures and models for this guide..
:::
Before we start, let's make sure you have your file structure set up:
<FolderView
:paths="[
'com.mojang/development_resource_packs/spear_RP/textures/items/spear.png',
'com.mojang/development_resource_packs/spear_RP/textures/entities/spear.png',
'com.mojang/development_resource_packs/spear_RP/entities/spear.json',
'com.mojang/development_resource_packs/spear_RP/attachables/spear.json',
'com.mojang/development_resource_packs/spear_RP/animations/spear_animation.json',
'com.mojang/development_resource_packs/spear_RP/texts/en_US.lang',
'com.mojang/development_resource_packs/spear_RP/manifest.json',
'com.mojang/development_resource_packs/spear_RP/pack_icon.png',
'com.mojang/development_behavior_packs/spear_BP/items/spear.json',
'com.mojang/development_behavior_packs/spear_BP/entities/spear.json',
'com.mojang/development_behavior_packs/spear_BP/pack_icon.png',
'com.mojang/development_behavior_packs/spear_BP/manifest.json'
]"
></FolderView>
Making custom spears is a really simple task. It was not simple for Koala Boy though. There are some scripting involved, but it doesn't do the main behaviors.
## Item
It can go without saying that you'd obviously need an item to make a spear, however we don't use some "basic" behaviors. Let's get an item file and let's add the following components. Let's start with the main components:
<CodeHeader>BP/items/spear.json</CodeHeader>
```json
{
//Use duration is the max time we can use the item.
"minecraft:use_duration": 3600,
//This component is what gives our spear the ability to 'draw' it like a bow
"minecraft:throwable": {
"min_draw_duration": 2,
"max_draw_duration": 4,
"scale_power_by_draw_duration": true
},
//What projectile to shoot when draw is complete
"minecraft:projectile": {
"projectile_entity": "wiki:thrown_iron_spear",
"minimum_critical_power": 1.0
},
//Durability of the spear.
"minecraft:durability": {
"max_durability": 125
}
}
```
## Spear Projectile
We can safely say that we got the important components for our spear. Next we move over to the projectile. This projectile will be a simple entity, with some added components and a runtime identifier to get the correct behaviors.
<Spoiler title="Projectile">
<CodeHeader>BP/entities/spear.json</CodeHeader>
```json
{
"format_version": "1.12.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:thrown_iron_spear",
"is_spawnable": false,
"is_summonable": true,
"is_experimental": false,
"runtime_identifier": "minecraft:snowball"
},
"component_groups": {
"wiki:give": {
"minecraft:instant_despawn": {}
}
},
"components": {
"minecraft:conditional_bandwidth_optimization": {
"default_values": {
"max_dropped_ticks": 10,
"max_optimized_distance": 100,
"use_motion_prediction_hints": true
}
},
"minecraft:hurt_on_condition": {
"damage_conditions": [
{
"cause": "lava",
"damage_per_tick": 4,
"filters": {
"operator": "==",
"subject": "self",
"test": "in_lava",
"value": true
}
}
]
},
"minecraft:physics": {},
"minecraft:projectile": {
"anchor": 1,
"gravity": 0.05,
"hit_sound": "bow.hit",
"offset": [
0,
-0.1,
0
],
"on_hit": {
"definition_event": {
"event_trigger": {
"event": "example:foo",
"target": "self"
}
},
"impact_damage": {
"damage": 7,
"destroy_on_hit": false,
"knockback": true,
"power_multiplier": 0.97,
"semi_random_diff_damage": false
},
"stick_in_ground": {
"shake_time": 0.35
}
},
"power": 3,
"should_bounce": true,
"stop_on_hurt": true
},
"minecraft:pushable": {
"is_pushable": false,
"is_pushable_by_piston": true
}
}
}
}
```
</Spoiler>
Here we got our simple projectile entity. We are missing one part to make this a useful projectile. There is no way for our player to pick it up from the ground. In order to do this, we need events and entity sensors:
<CodeHeader>BP/entities/spear.json</CodeHeader>
```json
{
"components": {
//Entity sensor detects if the projectile is on the ground, and if the player is near the entity.
//This will run an event when it's true
"minecraft:entity_sensor": {
"event": "wiki:give",
"event_filters": {
"all_of": [
{
"subject": "other",
"test": "is_family",
"value": "player"
},
{
"subject": "self",
"test": "on_ground",
"value": true
}
]
},
"minimum_count": 1,
"relative_range": false,
"sensor_range": 0.7
}
},
"events": {
/*
This event will despawn our projectile, and give our player a tag, which we will use in our script.
*/
"wiki:give": {
"sequence": [
{
"add": {
"component_groups": [
"wiki:give"
]
}
},
{
"randomize": [
{
"run_command": {
"command": [
"playsound random.pop @p",
"tag @p add iron_spear"
]
},
"weight": 90
}
]
}
]
}
}
}
```
Once we're done with out projectile entity, it's time to go to Resource Packs.
## Client Entity
We will be using a basic client entity file for our projectile with added code.
<Spoiler title="Client Entity">
<CodeHeader>RP/entities/spear.json</CodeHeader>
```json
{
"format_version": "1.10.0",
"minecraft:client_entity": {
"description": {
"identifier": "wiki:thrown_iron_spear",
"materials": {
"default": "entity_alphatest"
},
"textures": {
"default": "textures/entity/iron_spear"
},
"animations": {
"move": "animation.weapon.default_thrown"
},
"scripts": {
"animate": [
"move"
]
},
"geometry": {
"default": "geometry.stone_spear"
},
"render_controllers": [
"controller.render.default"
]
}
}
}
```
</Spoiler>
Inside our client entity file, you might have noticed that there is animations bound to it. This animation will make our projectile rotate as it flies.
:::warning
Make sure your entity model is modeled like the image bellow!
:::
![](/assets/images/items/spears/spear_model.png)
## Animation
The animation we use for our projectile isn't you normal entity animation. This one uses [molang](https://bedrock.dev/docs/stable/Molang) to define rotations.
<CodeHeader>BP/animations/spear.json</CodeHeader>
```json
{
"format_version": "1.8.0",
"animations": {
"animation.weapon.default_thrown": {
"loop": true,
"bones": {
"body": {
//This is some molang stuff. The animation uses this to rotate the model based on its current angle.
"rotation": ["-q.target_x_rotation", "-q.body_y_rotation", 0]
}
}
}
}
}
```
## Attachable
We will be using the Trident Attachable because it comes with item positions and use animations already. It should look like this:
<CodeHeader>BP/attachables/spear.json</CodeHeader>
```json
{
"format_version": "1.10.0",
"minecraft:attachable": {
"description": {
"identifier": "wiki:iron_spear",
"materials": {
"default": "entity_alphatest",
"enchanted": "entity_alphatest_glint"
},
"textures": {
"default": "textures/entity/iron_spear",
"enchanted": "textures/misc/enchanted_item_glint"
},
"geometry": {
"default": "geometry.stone_spear_item"
},
"animations": {
"wield": "controller.animation.trident.wield",
"wield_first_person": "animation.trident.wield_first_person",
"wield_first_person_raise": "animation.trident.wield_first_person_raise",
"wield_first_person_raise_shake": "animation.trident.wield_first_person_raise_shake",
"wield_first_person_riptide": "animation.trident.wield_first_person_riptide",
"wield_third_person": "animation.trident.wield_third_person",
"wield_third_person_raise": "animation.trident.wield_third_person_raise"
},
"scripts": {
"pre_animation": [
"v.charge_amount = math.clamp((q.main_hand_item_max_duration - (q.main_hand_item_use_duration - q.frame_alpha + 1.0)) / 10.0, 0.0, 1.0f);"
],
"animate": [
"wield"
]
},
"render_controllers": [
"controller.render.item_default"
]
}
}
}
```
## Script
Now that we've setup our spear, there is no way to damage the spear when it's thrown. To do this, we will make use of Script-API.
The script is really simple, and wouldn't require much brain power.
```js
import { world, ItemStack } from "@minecraft/server"
import { system } from "@minecraft/server";
//This prevents world crash
system.beforeEvents.watchdogTerminate.subscribe(data => {
data.cancel = true;
});
world.afterEvents.itemReleaseUse.subscribe(ev => {
//This is for multiplayer support
for (const player of world.getPlayers()){
//Basic variables to get the player inventory and held item.
let inv = player.getComponent( 'inventory' ).container
//Our itemStack to save our item. This also saves item data.
const itemStack = inv.getItem(player.selectedSlot);
//If the item we're holding is our spear, we run code.
if (itemStack?.typeId === 'wiki:iron_spear') {
var container = player.getComponent('inventory').container
//The new item to be given.
var newItem = new ItemStack("wiki:iron_spear");
var oldItem = container?.getItem(player.selectedSlot)
//Here's that tag!
player.removeTag("iron_spear")
}
//We subscribe a tick event to detect when we have the tag and if the item has durability less than the max.
let e = system.runInterval(() => {
if(player.hasTag("iron_spear") && itemStack?.typeId === 'wiki:iron_spear' && itemStack?.getComponent("durability").damage <= 125) {
player.removeTag("iron_spear")
//This gives our saved item (newItem) +1 durability each time we pick it up.
newItem.getComponent("durability").damage = oldItem.getComponent("durability").damage + 1;
container.setItem(player.selectedSlot, newItem);
//When we don't have the tag, we stop the tick event.
if(!player.hasTag("iron_spear")){
system.clearRun(e);
}}
})}
})
```
## Final Product
Once you've followed this guide, you should have your own working spear in-game.
![](/assets/images/items/spears/spear_first_person.png)
![](/assets/images/items/spears/spear_third_person.png)
Example Pack Download:
<BButton
link="https://github.com/Bedrock-OSS/wiki-addon/releases/download/download/custom_spear.mcaddon"
color=blue
>💾 Example Pack</BButton>

382
docs/wiki/items/throwable.md Normal file
View File

@@ -0,0 +1,382 @@
---
title: Throwable Items
category: Tutorials
tags:
- intermediate
mentions:
- Fabrimat
- MedicalJewel105
- Luthorius
- IlkinQafarov
- seeit360
- TheItsNameless
- SmokeyStack
- ThomasOrs
---
::: tip
This tutorial assumes you have a basic understanding of Molang, animation controllers and entity definitions.
:::
Items like the Splash Potion or the Trident are special items that can be thrown. Currently, there are two ways to accomplish something similar in your add-on, one that can be done in the stable release and one that needs the `Holiday Creator Features` experimental toggle to be enabled.
## Stable method
This method lets you detect the usage of an item through the `minecraft:food` component from an animation controller, and modifying the `player.json` you can then spawn an entity when that happens.
### The Item
First, you'll want to make the actual item:
<CodeHeader>BP/items/throwable_item.item.json</CodeHeader>
```json
{
"format_version": "1.16.0",
"minecraft:item": {
"description": {
"identifier": "wiki:throwable_item"
},
"components": {
"minecraft:max_stack_size": 16,
"minecraft:use_duration": 12000,
"minecraft:food": {
"can_always_eat": true
}
}
}
}
```
We can notice several things here:
- `format_version` must be `1.16.0`
- `minecraft:use_duration` should be a high number, in order to stop the eating sound to play and to prevent the player from eating the item
- `minecraft:food` is used to allow player to actually "use" the item, so we can detect it
Because the format version is `1.16.0`, your item needs an RP definition too:
<CodeHeader>RP/items/throwable_item.item.json</CodeHeader>
```json
{
"format_version": "1.16.0",
"minecraft:item": {
"description": {
"identifier": "wiki:throwable_item",
"category": "Equipment"
},
"components": {
"minecraft:icon": "throwable_item"
}
}
}
```
### The Entity
The entity will be the actual thrown item, and it will behave like a projectile.
Make sure to add snowball runtime identifier to make your projectile to actually be shoot, not spawned. You can also experiment with other projectile runtime id's.
<CodeHeader>BP/entities/throwable_item_entity.se.json</CodeHeader>
```json
{
"format_version": "1.16.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:throwable_item_entity",
"is_spawnable": false,
"is_summonable": true,
"is_experimental": false,
"runtime_identifier": "minecraft:snowball"
},
"components": {
"minecraft:collision_box": {
"width": 0.25,
"height": 0.25
},
"minecraft:projectile": {
"on_hit": {
"grant_xp": {
"minXP": 3,
"maxXP": 5
},
"impact_damage": {
"damage": 16
},
"remove_on_hit": {}
},
"power": 0.7,
"gravity": 0.03,
"angle_offset": -20.0,
"hit_sound": "glass"
},
"minecraft:physics": {},
"minecraft:pushable": {
"is_pushable": true,
"is_pushable_by_piston": true
},
"minecraft:conditional_bandwidth_optimization": {
"default_values": {
"max_optimized_distance": 80.0,
"max_dropped_ticks": 10,
"use_motion_prediction_hints": true
}
}
}
}
}
```
This entity is based on the Vanilla splash potion.
You can then customize its behavior by editing the `minecraft:projectile` component, in this case the thrown item will grant some exp and will damage any entity it will hit.
### The Animation Controller
The animation controller is responsible for detecting the usage of the item and for telling the player entity to spawn a throwable entity.
<CodeHeader>BP/animation_controllers/throwables.ac.json</CodeHeader>
```json
{
"format_version": "1.10.0",
"animation_controllers": {
"controller.animation.player.throwables": { // The ID we will reference in the player's entity description
"states": {
"default": {
"transitions": [
{
// Current "q.is_item_name_any" takes 3 arguments, first is slot name, second is slot id, third is the item we want to check for
"throw_item": "q.is_item_name_any('slot.weapon.mainhand', 0, 'wiki:throwable_item') && q.is_using_item"
// "q.is_using_item" returns 'true' or 'false', in our case if player uses item it is going to return 'true'
}
],
"on_entry": [
// Resets the player entity in order to be able to throw another item
"@s wiki:reset_player"
]
},
"throw_item": {
"transitions": [
{
"default": "1.0"
}
],
"on_entry": [
// Call the event in the player entity responsible of throwing the item
"@s wiki:throw_item",
// Remove the item from player's inventory
"/clear @s wiki:throwable_item -1 1"
]
}
}
}
}
}
```
#### player.json
:::tip
Always make sure that your `player.json` file is updated to the latest version available, depending on the game version you are working on.
You can do that [here](https://bedrock.dev/packs).
:::
:::warning
Do not edit/remove existing parts of the `player.json` file unless you know what you are doing, as it could (and probably will) break the game.
:::
Now, you have to register the animation controller to the `player.json` file:
<CodeHeader>BP/entities/player.json</CodeHeader>
```json
{
"format_version": "1.18.20",
"minecraft:entity": {
"description": {
"identifier": "minecraft:player",
"is_spawnable": false,
"is_summonable": false,
"is_experimental": false,
"scripts": {
"animate": [
"throwables_controller" // This should exactly match the same as the one below
]
},
"animations": {
"throwables_controller": "controller.animation.player.throwables" // ID as referenced in animation controller file
}
},
"components": {
"minecraft:breathable": { // keeps breath timer bubbles from appearing
"total_supply": 15,
"suffocate_time": -1,
"inhale_time": 3.75,
"generates_bubbles": false
}
},
...
}
```
Then, you need to add all the events and component groups to the `player.json` file:
<CodeHeader>BP/entities/player.json#minecraft:entity</CodeHeader>
```json
"component_groups": {
"wiki:throw_entity": { // Contains a component that will spawn the entity
"minecraft:spawn_entity": {
"entities": {
"min_wait_time": 0,
"max_wait_time": 0,
"single_use": true,
"spawn_entity": "wiki:throwable_item_entity",
"num_to_spawn": 1
}
}
}
},
"events": {
"wiki:reset_player": {
"remove": {
"component_groups": [
"wiki:throw_entity"
]
}
},
"wiki:throw_item": {
"add": {
"component_groups": [
"wiki:throw_entity"
]
}
}
}
```
## Experimental method
This method requires the `Holiday Creator Features` experimental toggle to be enabled.
### The Item
<CodeHeader>BP/items/throwable_item.item.json</CodeHeader>
```json
{
"format_version": "1.16.100",
"minecraft:item": {
"description": {
"identifier": "wiki:throwable_item"
},
"components": {
"minecraft:max_stack_size": 16,
"minecraft:on_use": {
"on_use": {
"event": "throw"
}
},
"minecraft:icon": {
"texture": "apple"
}
},
"events": {
"throw": {
"shoot": {
"projectile": "wiki:throwable_item_entity",
"launch_power": 2,
"angle_offset": 1
},
"swing": {},
"decrement_stack": {},
"run_command": {
"command": [
"playsound fire.ignite",
"playsound mob.witch.throw"
]
}
}
}
}
}
```
We can notice several things here:
- `format_version` must be `1.16.100`
- `minecraft:on_use` will call an event every time the item is used (right-clicked)
In the event:
- `shoot` will shoot our entity
- `swing` will run the swing animation on the player
- `decrement_stack` will remove one item from the player's inventory
- `run_command` will execute commands when the item is shot, like playing sounds
### The Entity
The entity file is the same as the Stable version.
<Spoiler title="BP/entities/throwable_item_entity.se.json">
<CodeHeader>BP/entities/throwable_item_entity.se.json</CodeHeader>
```json
{
"format_version": "1.16.0",
"minecraft:entity": {
"description": {
"identifier": "wiki:throwable_item_entity",
"is_spawnable": false,
"is_summonable": true,
"is_experimental": false,
"runtime_identifier": "minecraft:snowball"
},
"components": {
"minecraft:collision_box": {
"width": 0.25,
"height": 0.25
},
"minecraft:projectile": {
"on_hit": {
"grant_xp": {
"minXP": 3,
"maxXP": 5
},
"impact_damage": {
"damage": 16
},
"remove_on_hit": {}
},
"power": 0.7,
"gravity": 0.03,
"angle_offset": -20.0,
"hit_sound": "glass"
},
"minecraft:physics": {},
"minecraft:pushable": {
"is_pushable": true,
"is_pushable_by_piston": true
},
"minecraft:conditional_bandwidth_optimization": {
"default_values": {
"max_optimized_distance": 80.0,
"max_dropped_ticks": 10,
"use_motion_prediction_hints": true
}
}
}
}
}
```
</Spoiler>
## Conclusion
Once you have your throwable item you can start trying several things, like playing with its power, effects, animations or combining it with an [AOE Cloud](/entities/introduction-to-aec). The only limit is your imagination.

Some files were not shown because too many files have changed in this diff Show More