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

完整版BedrockWiki镜像！

Browse Source
This commit is contained in:
boybook
2025-03-20 11:52:46 +08:00
parent 1994c41f01
commit bf9aa4b056
214 changed files with 9042 additions and 8867 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
docs/wiki/meta/addon-performance.md
View File

@@ -1,5 +1,5 @@
---
title: Addon Performance
title: 附加包性能优化
mentions:
- SirLich
- Joelant05
@@ -8,211 +8,212 @@ mentions:
- SmokeyStack
---
# 附加包性能优化
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
::: warning
This page was compiled primarily using community feedback from multiple sources. As a result, some information may be generalized, subjective, or conflicting. Always use your own best judgment when optimizing your addons. This page is not a substitute for testing your addon on a wide range of devices.
本页内容主要基于多方社区反馈整理。因此部分信息可能存在概括性、主观性或矛盾性。优化附加包时请始终自行判断。本页面不能替代在多种设备上实际测试附加包性能。
:::
Performance in addons is crucial, as the most technically fantastic addon is mainly useless if the majority of the player base cannot experience it. When developing addons, it should always be considered that many Bedrock players will be experiencing your addon on a significantly lower power device than you are developing on. This is especially true for mobile users. Therefore, addons should be developed with performance in mind and tested for performance on lower-end devices when possible.
附加包性能至关重要，因为即使技术上最出色的附加包，如果大多数玩家设备无法流畅运行也将失去意义。开发附加包时需时刻谨记，许多基岩版玩家使用性能远低于开发设备的终端进行游戏，移动端用户尤为明显。因此应从性能角度设计附加包，并尽可能在低端设备上进行测试。
This guide is a non-exhaustive list of specific performance considerations separated by the various subsystems of Bedrock Edition. No single point should be taken as a hard and fast rule. Instead, these performance considerations should help you to recognize potential areas for improvement.
本指南按基岩版各子系统分类，列出非详尽性能考量事项。各条目不应视为铁律，而应作为识别潜在优化领域的参考。
## Biomes and Features
## 生物群系与特征生成
### Biomes
### 生物群系
- The biome system is generally efficient
- Large values for heightmaps are usually handled gracefully
- The component `climate` creates large particle storms
- 生物群系系统整体效率较高
- 通常能妥善处理高度图的大数值
- `climate`组件会产生大量粒子风暴
### Features
### 特征生成
- Biomes generally cause less lag than feature generation.
- Hundreds of iterations per chunk of a multi-block feature have been achieved at a low-performance cost.
- Thousands of iterations per chunk of multi-block features negatively impact gameplay.
- Hundreds of thousands of iterations per chunk of a single-block feature have been achieved at a low-performance cost.
- Thousands of instances of features *per chunk* comes at little cost.
- Tens of thousands of feature instances *per chunk* yields a noticeable impact on chunk loading.
- Hundreds of thousands of instances of features *per chunk* slows chunk loading to an unbearable crawl.
- 生物群系生成通常比特征生成更少卡顿
- 单个区块内执行数百次多方块特征迭代性能损耗较低
- 单个区块内数千次多方块特征迭代将显著影响游戏体验
- 单个区块内执行数十万次单方块特征迭代性能损耗较低
- 单个区块内数千个特征实例性能成本较低
- 单个区块内数万个特征实例会显著影响区块加载
- 单个区块内数十万特征实例将导致区块加载极度缓慢
## Blocks
## 方块
### Materials
### 材质
- The minimum needed material type with regards to rendering should always be utilized
> `alpha_blend` performance is worse than `alpha_test`, which is worse than `opaque`
- 应始终使用渲染需求最低的材质类型
> `alpha_blend`性能差于`alpha_test`，后者又差于`opaque`
### Quantity and Type
### 数量与类型
- Flowing liquids should be avoided and minimized
- 应尽量避免并减少流动液体
### Updates
### 更新
- Block updates should be minimized
- 应尽量减少方块更新
## Commands
## 命令
### Quantity and Type
### 数量与类型
- Minimize the number of commands run per tick
> `/effect` and `/gamemode` run every tick are avoidable and have a significant performance impact
- Large clones, fills and structure loads during runtime should be avoided
> Breaking these more extensive operations into multiple commands distributed over multiple ticks will avoid lag spikes, consider using structure loading animations
- 最小化每tick执行的命令数量
> 每个tick执行`/effect`和`/gamemode`等命令应避免，这些操作对性能影响显著
- 应避免在运行时进行大规模clone、fill和结构加载
> 将大型操作拆分为多tick执行的多个命令可避免卡顿，建议使用结构加载动画
### Selectors
### 选择器
- Care should be taken to ensure a function is not executed on too many entities, and therefore too many times
- Executing a scoreboard command outweighs the cost of running an entity selector multiple times
- Using c=1 to ensure the selector stops when it finds one entity may improve performance
- When executing multiple commands with the same selector, use a function instead to avoid repeatedly resolving the same selector
- 需注意避免对过多实体执行函数导致执行次数过多
- 执行记分板命令的成本高于多次运行实体选择器
- 使用c=1确保选择器在找到第一个实体后停止可提升性能
- 使用相同选择器执行多个命令时，应改用函数避免重复解析
### Tags vs. Scoreboards
### 标签与记分板
- Scoreboards perform better at a large scale than tags
- 记分板在大规模使用时性能优于标签
## Entities
## 实体
- Entities generally have one of the most significant performance impacts by subsystem and thus should be minimized where possible
- 实体通常是各子系统中性能影响最大的要素，应尽可能减少
### Components
### 组件
- Pathfinding on flying mobs has a significant performance cost
- Flying mobs in general encounter performance problems
> Faking flying mobs via animation should be considered if possible
- 飞行生物寻路计算性能消耗显著
- 飞行生物通常存在性能问题
> 如有可能，建议通过动画模拟飞行生物
### Dummy Entities
### 虚拟实体
- Dummy entities generally have equal performance impact to proper entities, except when excluding heavy components like pathfinding
- 虚拟实体与常规实体性能影响相当（不含寻路等重型组件时）
### Geometry
### 几何结构
#### Bones
#### 骨骼
- No performance impact has been observed regarding bone count
- 骨骼数量未观测到明显性能影响
#### Elements
#### 元素
- Element count is not generally an issue, except in extreme cases when thousands of elements are reached
- 除极端情况（数千元素）外，元素数量通常不成问题
### Materials
### 材质
- The minimum material required to achieve the desired effect should always be used
- When in doubt, refer to the material definition files to get an idea of the costs of various materials, taking the material inheritance system into account
- 应始终使用实现预期效果所需的最低材质
- 不确定时可参考材质定义文件，同时考虑材质继承系统
### Quantity
### 数量
- Loaded entities at any given time should be minimized
> Below 30 is optimal
- 应尽量减少任意时刻加载的实体数量
> 保持30个以下为最佳
## Lighting
## 光照
### Map Considerations
### 地图设计
- Hollow areas will cause lag due to lighting calculations even if you don't see them
> Avoid this by filling in unused enclosed areas
- Keeping the map set to day or night will avoid lighting recalculation
- 空心区域即使不可见仍会导致光照计算卡顿
> 填充未使用的封闭空间可避免此问题
- 保持昼夜恒定可避免光照重新计算
### Sources
### 光源
- Bedrock lighting is calculated dynamically, meaning different light sources have different performance costs
> Light blocks are the most performant because they lack particles, rendering, and particular state logic
- 基岩版动态计算光照，不同光源性能成本不同
> 光源方块性能最佳（无粒子、渲染和特殊状态逻辑）
> Torches are a minor performance issue because they emit particles, render, and have particular state logic dependent on what block they connect to
> 火把因产生粒子、渲染和连接状态逻辑存在较小性能问题
> Custom light blocks with minimal components are a reasonable compromise between performance and aesthetics
> 含最少组件的自定义光源方块是性能与美观的合理折中
#### Comparison Table
#### 对比表格
| Light Source | Score | Redstone Updates | Animted Texture | Light Updates | Tick Updates | Particles | Renders |
| ---------------: | :---: | :--------------: | :-------------: | :-----------: | :----------: | :-------: | :-----: |
| Light Blocks | 1 | False | False | True | False | False | False |
| Lanterns | 4 | False | True | True | True | False | True |
| Custom Blocks | 2 | False | False | True | False | False | True |
| Mushrooms | 3 | False | False | True | True | False | True |
| Redstone Lamps | 3 | True | False | True | False | False | True |
| Glowstone | 3 | True | False | True | True | False | True |
| Sea Lanterns | 4 | False | True | True | True | False | True |
| Torches | 4 | False | False | True | True | True | True |
| Redstone Torches | 5 | True | False | True | True | True | True |
| 光源类型 | 评分 | 红石更新 | 动画纹理 | 光照更新 | Tick更新 | 粒子效果 | 渲染 |
| ---------------: | :--: | :------: | :------: | :------: | :------: | :------: | :--: |
| 光源方块 | 1 | 否 | 否 | 是 | 否 | 否 | 否 |
| 灯笼 | 4 | 否 | 是 | 是 | 是 | 否 | 是 |
| 自定义方块 | 2 | 否 | 否 | 是 | 否 | 否 | 是 |
| 蘑菇 | 3 | 否 | 否 | 是 | 是 | 否 | 是 |
| 红石灯 | 3 | 是 | 否 | 是 | 否 | 否 | 是 |
| 荧石 | 3 | 是 | 否 | 是 | 是 | 否 | 是 |
| 海晶灯笼 | 4 | 否 | 是 | 是 | 是 | 否 | 是 |
| 火把 | 4 | 否 | 否 | 是 | 是 | 是 | 是 |
| 红石火把 | 5 | 是 | 否 | 是 | 是 | 是 | 是 |
## Molang
### Recursion
### 递归
- Minimize use of recursion when possible
- Intense nested loop structures will cause performance issues
- Use break to escape loops when possible
- 尽量减少递归使用
- 深度嵌套循环结构会导致性能问题
- 适时使用break跳出循环
### Structs
### 结构体
- Avoid making structs too deep, as there is a performance cost with each layer
- 避免结构体过深，每层嵌套均有性能损耗
### Variables
### 变量
- Use temp variables when possible to minimize variables loaded in memory
- Consider how often variables are calculated based on script type
- 尽量使用临时变量减少内存占用
- 根据脚本类型考虑变量计算频率
## Textures
## 纹理
### texture_list.json
- Tons of textures badly affect game performance. Create a [`texture_list.json`](/concepts/textures-list) file.
- 过多纹理严重影响性能，请创建[`texture_list.json`](/wiki/concepts/textures-list)文件
### Quantity
### 数量
- No more than 3000 textures should be used
> This is due to limits imposed by Render Dragon
- 建议不超过3000个纹理
> Render Dragon引擎限制为4096个纹理，1.16版本原版已有800个
> Render Dragon has a 4096 texture quantity limit, and there are 800 vanilla textures as of 1.16
### 分辨率
### Resolution
- 最大支持16384x16384
- 推荐最大4096x4096以保证低端设备兼容性
- 注意纹理图集化处理，大尺寸纹理可能影响低端设备图集生成
- 根据可视距离需求确定必要纹理尺寸
- The maximum texture resolution is 16384x16384
- The recommended maximum texture resolution is 4096x4096 to maintain compatibility with low-end devices
- Keep in mind that textures are atlased, and larger textures can mess with atlas generation on lower-end devices
- Only make textures as significant as needed to convey the detail needed at the needed distance
## 交易系统
## Trades
村民交易在达到60项以上时会导致性能问题甚至全设备崩溃。建议拆分交易至多个村民或自定义实体/NPC，测试表明30项交易是安全阈值。
*可能与JSON界面系统有关*
Villager trades cause performance issues and even crashes on all devices at 60 trades or greater. Avoid tons of trades for one entity.
Your best bet to resolve this issue is to split your trades in half and move them to another villager or custom entity/npc, 30 trades is a good safe number from testing.
*probably JSON UI issues*
## 音效
## Sounds
### 数量
### Count
- 已注册音效总数会影响性能
- Total registered sounds are reported to have an impact on performance
### 压缩
### Compression
- 音效压缩显著减小包体积
- 在Switch等老旧/低功耗设备上效果明显
- 基岩版使用的FMod简单API会将所有音效解压为WAV格式后加载至内存，CPU性能无提升
> 流式音频不在此列
- Sound compression is exceptionally beneficial to pack size
- This is especially noticeable on older and low power devices, such as the Switch
- The FMod simple API utilized by Bedrock decompresses all sounds into WAV before loading into RAM, meaning no CPU performance improvement in this respect
> If audio is streamed, this does not occur
### 流式处理
### Streaming
- 体积超过500KB或时长超过1分钟的音效应采用流式处理
- As general guidance, sounds over 500kb in size or 1 minute in length should be streamed
## 红石
## Redstone
### 区块边界
### Chunk Boundaries
- 应避免红石电路跨越区块边界
- Crossing chunk boundaries with Redstone should be avoided
### 命令方块
### Command Blocks
- 构建大型命令链时应垂直堆叠于单个区块内
- 尽可能用函数和行为包替代命令方块
- When creating large command blockchains, stack vertically and in a single chunk
- Minimize command block use in favor of functions and behaviors where possible
## 常加载区域
## Ticking Areas
- 总区块数比常加载区域更需关注
- 非必要时应避免动态区域
- 最佳实践是将常加载区域限制在单个区块
> 所有持续运行的红石装置应置于此区块
- 通过/testforblock测试并及时卸载不再需要的常加载区域
- Total chunks are of more significant concern than ticking areas
- Dynamic areas should be avoided unless necessary
- Best practice is to minimizing the ticking area to one chunk if possible
> All always-on Redstone should fit in this ticking chunk
- Unload ticking areas when they are no longer needed, testing via /testforblock
## 文件管理
## Files
- Tons of files can badly affect game performance. Create a [`contents.json`](/concepts/contents) file.
- 过多文件严重影响性能，请创建[`contents.json`](/wiki/concepts/contents)文件

310
docs/wiki/meta/jq.md
View File

File diff suppressed because one or more lines are too long

176
docs/wiki/meta/style-guide.md
View File

@@ -1,5 +1,5 @@
---
title: Style Guide
title: 样式指南
mentions:
- SirLich
- solvedDev
@@ -7,118 +7,121 @@ mentions:
- ChibiMango
---
This document will present the officially supported Bedrock-Wiki style guide for addon-creation. This guide aims to promote best practices while creating addons and create a consistent format for everyone to follow.
# 样式指南
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
本文档将介绍基岩版Wiki官方推荐的附加包开发样式指南。本指南旨在推广附加包开发的最佳实践，并为开发者提供统一的格式规范。
:::tip
The style guide is a living, breathing document, which will evolve as addon-creation evolves. Please get in touch if you think something needs to be updated or changed!
本样式指南是持续更新的动态文档，将随着附加包开发技术的发展而不断完善。如果您有任何更新建议，欢迎随时联系我们！
:::
## Folder Structure
## 文件夹结构
- No spaces in your file paths. `use_underscores`.
- No `CAPITALS` in your identifiers, file names, or folder names.
- The total character length of any path must not exceed 80 characters (console limitation).
- Content folders should use consistent pluralization: Don't mix and match.
- 文件路径中不要使用空格，使用下划线
- 标识符、文件名和文件夹名不要使用全大写字母
- 任何路径的总字符长度不得超过80个字符（控制台限制）
- 内容文件夹应保持统一的复数形式：不要混合使用单复数
## Identifiers
## 标识符规范
Do not use identifiers that begin with a number, and especially don't use an identifier that is _only_ a number. This applies to entities, component_groups, events, and anything else that takes a `namespace:name` pair.
不要使用以数字开头的标识符，尤其不要使用纯数字作为标识符。此规则适用于实体（entities）、组件组（component_groups）、事件（events）以及其他所有使用`命名空间:名称`格式的内容。
## File and Folder names
## 文件与文件夹命名规范
| Concept | Example Identifier |
| -------------------- | -------------------------- |
| Behavior Pack | dragons_BP |
| Resource Pack | dragons_RP |
| Geometry | dragon.geo.json |
| Animation | dragon.animation.json |
| Animation Controller | dragon.ac.json |
| RP Entity | dragon.ce.json |
| BP Entity | dragon.se.json |
| Item 1.16.100+ | dragon_tooth.item.json |
| BP Item | dragon_tooth.item.bp.json |
| RP Item | dragon_tooth.item.rp.json |
| Render Controller | dragon.rc.json |
| Loot Table | dragon.loot.json |
| Recipe | dragon_saddle.recipe.json |
| Spawn Rules | dragon.spawn.json |
| Trade Table | dragon.trade.json |
| Particles | dragon_magic.particle.json |
| Texture | dragon.png |
| Gametest | dragonTest.js |
| 概念 | 示例标识符 |
| --------------------- | -------------------------- |
| 行为包（Behavior Pack） | dragons_BP |
| 资源包（Resource Pack） | dragons_RP |
| 几何模型（Geometry） | dragon.geo.json |
| 动画（Animation） | dragon.animation.json |
| 动画控制器（Animation Controller） | dragon.ac.json |
| 资源包实体（RP Entity） | dragon.ce.json |
| 行为包实体（BP Entity） | dragon.se.json |
| 物品（1.16.100+） | dragon_tooth.item.json |
| 行为包物品（BP Item） | dragon_tooth.item.bp.json |
| 资源包物品（RP Item） | dragon_tooth.item.rp.json |
| 渲染控制器（Render Controller） | dragon.rc.json |
| 战利品表（Loot Table） | dragon.loot.json |
| 合成配方（Recipe） | dragon_saddle.recipe.json |
| 生成规则（Spawn Rules） | dragon.spawn.json |
| 交易表（Trade Table） | dragon.trade.json |
| 粒子效果（Particles） | dragon_magic.particle.json |
| 纹理贴图（Texture） | dragon.png |
| 游戏测试（Gametest） | dragonTest.js |
## Namespaces
## 命名空间规范
A suitable namespace should be unique to you or your team. 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.
合适的命名空间应具有开发者唯一性。使用`mob`、`cars`、`content`或`custom`等通用词汇作为命名空间是**不恰当**的，因为这些名称可能与其他开发者重复。
`minecraft` and `minecon` are reserved. Don't use these.
`minecraft`和`minecon`为保留命名空间，请勿使用。
For personal projects, use a convenient version of your player name, and for team projects, use a suitable version of your team name.
个人项目建议使用玩家ID的变体，团队项目建议使用团队名称的变体。
When multiple developers work on a project together, the namespace should always be shared. If credit is required, use sub-indexing: `minetite.sirlich:dragon`
多人协作开发时应共享命名空间。如需注明贡献者，可以使用子索引形式：`minetite.sirlich:dragon`
Where to use name-spaces:
需要使用命名空间的场景：
- entities
- particles
- component-groups
- events
- 实体（entities）
- 粒子效果（particles）
- 组件组（component-groups）
- 事件（events）
When not to use namespaces:
不需要使用命名空间的场景：
- do not include your namespace in any folder path or file-name
- 不要在文件夹路径或文件名中包含命名空间
## Sub-indexing
## 子索引规范
Sub indexing is the use of `.` to separate chained concepts. Sub-indexing should go in descending order from big to small:
子索引使用`.`符号分隔层级概念，应按照从宏观到微观的降序排列：
✔️ `animation.controller.dragon.flying.taking_off`
❌ `animation.controller.dragon_take_off_flying`
When using sub-indexing, use `_` as space, not another `.`.
使用子索引时，使用`_`替代空格，不要使用多个`.`：
✔️ `animation.controller.dragon.flying.taking_off`
❌ `animation.controller.dragon.flying.taking.off`
You can use sub-indexing in your entities:
实体标识符可以使用子索引：
`sirlich:dragon.drake`
## Groups and Events should complement each other
## 组件组与事件的对应关系
| Group | Event |
| ------------ | ---------------------- |
| sirlich:wild | ✔️ sirlich:become_wild |
| sirlich:wild | ❌ sirlich:wild |
| sirlich:tame | ✔️ sirlich:on_tame |
| sirlich:tame | ❌ sirlich:tame |
| 组件组 | 事件 |
| -------------- | ---------------------- |
| sirlich:wild | ✔️ sirlich:become_wild |
| sirlich:wild | ❌ sirlich:wild |
| sirlich:tame | ✔️ sirlich:on_tame |
| sirlich:tame | ❌ sirlich:tame |
## Short-Names should be Generic
## 短名称应保持通用性
Short-names are file-specific identifiers, which are used to map between an identifier and a pretty name. They are handy because they allow us to re-use animation controllers and render controllers. For this reason, your short-names should be generic.
短名称是文件内部的标识符，用于映射具体资源路径。通用短名称有助于复用动画控制器和渲染控制器：
✔️ `"sit": "animation.dragon.sit"`
❌ `"dragon_sitting": "animation.dragon.sit"`
When we make short-names of this form, we can use a generic "sit" animation controller for all of them since we can use the `sit` short-name to play the sit animation.
使用通用短名称后，我们可以为所有需要"坐下"动画的对象复用同一个"sit"动画控制器。
## Functions should be nested
## 函数的嵌套规范
You can put functions in folders to achieve this.
通过文件夹结构实现函数嵌套：
✔️ `function teleport/zone/hell`
❌ `function teleport_hellzone`
## Group animations files when possible
## 动画文件的组合规范
Example:
示例：
<CodeHeader></CodeHeader>
```json
::: code-group
```json [示例动画文件]
{
"format_version": "1.8.0",
"animations": {
@@ -128,8 +131,9 @@ Example:
}
}
```
:::
## Split textures by path, not name
## 纹理路径组织规范
✔️ `textures/dragon/red`
@@ -137,31 +141,31 @@ Example:
✔️ `textures/npc/dragon_hunter/archer`
❌ `textures npc/dragon_hunter_archer`
❌ `textures/npc/dragon_hunter_archer`
## .lang File Comments
## .lang文件注释规范
Comments intended for the localizer should always be in-line, in the following format:
面向本地化人员的注释应使用行内格式：
`the.key=The string<\t>## Comment, intended for the one localizing.`
`the.key=字符串内容<\t>## 注释内容，供本地化人员参考`
`<\t>` represents a tab-character.
`<\t>`表示制表符。
Own-line comments can be used for organizational purposes but should not store localization-critical information.
独立行注释可用于组织结构，但不要存储关键本地化信息。
## Acronyms when discussing
## 常用缩略词对照表
| Acronym | Concept |
| ------- | ---------------------------------- |
| BP | Behavior Pack |
| RP | Resource pack |
| VRP | Vanilla Resource Pack |
| VBP | Vanilla Behavior Pack |
| AC | Animation Controller |
| RPAC | Resource Pack Animation Controller |
| BPAC | Behavior Pack Animation Controller |
| BB | Blockbench |
| BDS | Bedrock Dedicated Server |
| FPV | First Person View |
| RD | Render Dragon |
| VSCode | Visual Studio Code |
| 缩略词 | 完整名称 |
| ------ | --------------------------- |
| BP | 行为包（Behavior Pack） |
| RP | 资源包（Resource Pack） |
| VRP | 原版资源包（Vanilla Resource Pack） |
| VBP | 原版行为包（Vanilla Behavior Pack） |
| AC | 动画控制器（Animation Controller） |
| RPAC | 资源包动画控制器（Resource Pack Animation Controller） |
| BPAC | 行为包动画控制器（Behavior Pack Animation Controller） |
| BB | Blockbench建模软件 |
| BDS | 基岩版专用服务器（Bedrock Dedicated Server） |
| FPV | 第一人称视角（First Person View） |
| RD | Render Dragon渲染引擎 |
| VSCode | Visual Studio代码编辑器 |

198
docs/wiki/meta/useful-links.md
View File

@@ -1,5 +1,5 @@
---
title: Useful Links
title: 实用链接
mentions:
- SirLich
- MedicalJewel105
@@ -17,11 +17,15 @@ mentions:
- zheaEvyline
---
There is loads of helpful information about Bedrock Development online, but sometimes it is hard to find! We will do our best to keep this list up to date as we continue to find useful content.
# 实用链接
Important links have a ⭐.
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
## Discord Links
网络上存在大量关于基岩版开发的实用信息，但有时却难以寻觅！我们将持续更新这份清单，尽力保持内容的最新性。
重要链接标有⭐符号。
## Discord相关链接
- ⭐ [Bedrock Add-Ons](https://discord.gg/46JUdQb)
- ⭐ [Bedrock OSS](https://discord.gg/XjV87YN)
@@ -43,115 +47,113 @@ Important links have a ⭐.
- [Minecraft RTX](http://discord.gg/vNWc3Hh)
- [Mojang Bug Tracker](https://discord.gg/rpCyfKV)
## Software (installed)
## 本地安装软件
- ⭐ [Blockbench: A boxy 3D model editor](https://blockbench.net/)
- ⭐ [bridge. Addon Editor](https://bridge-core.github.io/)
- ⭐ [VSCode Editor](https://code.visualstudio.com/)
- ⭐ [Regolith](https://github.com/Bedrock-OSS/regolith)
- [CoreCoder [Code Editor]](https://hanprog.itch.io/core-coder)
- [Feature Rule Generator v2 (paid version)](https://machine-builder.itch.io/frg-v2)
- [Feature Rule Generator v2 (free version)](https://drive.google.com/file/d/1rwQTtzgpWiqCS9ecO_j-qcxjdQvWSXgi/view)
- [Add-on JSON Generator (paid)](https://kaifireborn.itch.io/add-on-json-generator)
- [NBT Editor](https://www.universalminecrafteditor.com/)
- [World Converter (paid)](https://www.universalminecraftconverter.com/download)
- [Chunker (World Converter)](https://chunker.app/)
- ⭐ [Blockbench：一款专为方块风格设计的3D建模工具](https://blockbench.net/)
- ⭐ [bridge. 附加包编辑器](https://bridge-core.github.io/)
- ⭐ [VSCode 代码编辑器](https://code.visualstudio.com/)
- ⭐ [Regolith（快速构建工具链）](https://github.com/Bedrock-OSS/regolith)
- [CoreCoder [代码编辑器]](https://hanprog.itch.io/core-coder)
- [Feature Rule Generator v2（付费版）](https://machine-builder.itch.io/frg-v2)
- [Feature Rule Generator v2（免费版）](https://drive.google.com/file/d/1rwQTtzgpWiqCS9ecO_j-qcxjdQvWSXgi/view)
- [Add-on JSON Generator（付费）](https://kaifireborn.itch.io/add-on-json-generator)
- [NBT 编辑器](https://www.universalminecrafteditor.com/)
- [世界转换器（付费）](https://www.universalminecraftconverter.com/download)
- [Chunker（世界格式转换器）](https://chunker.app/)
- [NBT Studio](https://github.com/tryashtar/nbt-studio)
- [BedrockLauncher (Bedrock version switcher)](https://bedrocklauncher.github.io/)
- [ResourcePack Converter [App]](https://converter.bedrockhub.io)
- [BedrockConnect [App]](https://bedrockconnect.bedrockhub.io)
- [BedrockLauncher（版本切换工具）](https://bedrocklauncher.github.io/)
- [资源包转换器 [应用]](https://converter.bedrockhub.io)
- [BedrockConnect [应用]](https://bedrockconnect.bedrockhub.io)
## Bedrock Tools Websites
## 基岩版在线工具
- ⭐ [Snowstorm Particle Generator](https://jannisx11.github.io/snowstorm/)
- ⭐ [Loot Table Generator](https://bedrock-oss.github.io/bedrock-loot-gen/)
- [Apply Loot Tables to Structures](https://mcbe-essentials.github.io/structure-editor/loot-tabler)
- [Structure Editor](https://mcbe-essentials.github.io/structure-editor/)
- [Convert MCSTRUCTURE to MCFUNCTION](https://mcbe-essentials.github.io/structure-to-function/)
- [Crafting Recipe Generator](https://crafting.thedestruc7i0n.ca/)
- [Trade Table Generator](https://mcbe-essentials.github.io/trade-table-editor/)
- [World Packager](https://mcbe-essentials.github.io/world-packager/)
- [Manifest Generator](https://bedrock-manifest.web.app/)
- [Foxynotail Tools](https://www.foxynotail.com/tools/)
- [.lang File Generator](https://solveddev.github.io/AnyLanguage/)
- [behavior-builder (beta)](https://stirante.com/behavior/index)
- [controller-builder (beta)](https://stirante.com/controller/index)
- [MCPACK Generator](https://mcbe-essentials.github.io/instant-pack/)
- [Molang Grapher](https://jannisx11.github.io/molang-grapher/)
- [Molang Playground](https://bridge-core.github.io/molang-playground/)
- [Dialogue Generator](https://mcbe-essentials.github.io/dialogue-editor/)
- [Selector Generator](https://mcbe-essentials.github.io/selector-generator/)
- [Addon Obfuscator](https://tools.pixelpoly.co/obfuscator)
- ⭐ [Snowstorm 粒子效果生成器](https://jannisx11.github.io/snowstorm/)
- ⭐ [战利品表生成器](https://bedrock-oss.github.io/bedrock-loot-gen/)
- [为结构添加战利品表](https://mcbe-essentials.github.io/structure-editor/loot-tabler)
- [结构编辑器](https://mcbe-essentials.github.io/structure-editor/)
- [MCSTRUCTURE转MCFUNCTION](https://mcbe-essentials.github.io/structure-to-function/)
- [合成配方生成器](https://crafting.thedestruc7i0n.ca/)
- [村民交易表生成器](https://mcbe-essentials.github.io/trade-table-editor/)
- [世界打包工具](https://mcbe-essentials.github.io/world-packager/)
- [清单文件生成器](https://bedrock-manifest.web.app/)
- [Foxynotail工具集](https://www.foxynotail.com/tools/)
- [.lang语言文件生成器](https://solveddev.github.io/AnyLanguage/)
- [行为包构建器（测试版）](https://stirante.com/behavior/index)
- [控制器构建器（测试版）](https://stirante.com/controller/index)
- [MCPACK快速生成](https://mcbe-essentials.github.io/instant-pack/)
- [Molang可视化工具](https://jannisx11.github.io/molang-grapher/)
- [Molang调试沙盒](https://bridge-core.github.io/molang-playground/)
- [对话系统生成器](https://mcbe-essentials.github.io/dialogue-editor/)
- [目标选择器生成器](https://mcbe-essentials.github.io/selector-generator/)
- [附加包混淆工具](https://tools.pixelpoly.co/obfuscator)
## Documentation
## 文档资源
- ⭐ [bedrock.dev](https://bedrock.dev/)
- ⭐ [Minecraft Creator Portal](https://docs.microsoft.com/en-us/minecraft/creator/)
- ⭐ [Minecraft Community Wiki](https://minecraft.wiki)
- [Mcbehub](https://mcbehub.com/category/realmdocs)
- [Bedrock Texture Pack Template](https://github.com/Brennian/BedrockTexturesTemplate)
- [Documentation Graveyard (removed components)](https://gist.github.com/destruc7i0n/ea1a6a7f97f0986d9326c58246f96fa3)
- ⭐ [bedrock.dev（权威文档）](https://bedrock.dev/)
- ⭐ [Minecraft创作者门户](https://docs.microsoft.com/en-us/minecraft/creator/)
- ⭐ [Minecraft社区Wiki](https://minecraft.wiki)
- [Mcbehub文档站](https://mcbehub.com/category/realmdocs)
- [基岩版材质包模板](https://github.com/Brennian/BedrockTexturesTemplate)
- [已弃用组件文档库](https://gist.github.com/destruc7i0n/ea1a6a7f97f0986d9326c58246f96fa3)
### Getting Started With Your First Add-On
### 附加包开发入门
- [Getting Started with Add-On Development for Bedrock Edition](https://learn.microsoft.com/en-us/minecraft/creator/documents/gettingstarted): These guides show you exactly how to build your first resource pack and your first behavior pack from start to finish.
- [Molang: a Beginner's Guide](https://learn.microsoft.com/en-us/minecraft/creator/documents/molangbeginnersguide): Molang is a Minecraft programming language that can be useful for writing some advanced add-ons.
- [Introduction to the GameTest Framework](https://learn.microsoft.com/en-us/minecraft/creator/documents/gametestgettingstarted): This is the best way to test games, and it uses JavaScript, the most popular programming language in the world!
- [Build a gameplay experience with TypeScript](https://learn.microsoft.com/en-us/minecraft/creator/documents/scriptinggettingstarted): TypeScript is Microsoft's copy of JavaScript. Writing add-ons in TypeScript allows you to add any functionality you can imagine!
- [@minecraft/server Module](https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/mojang-minecraft/mojang-minecraft): This module and the others near it are how we can access Minecraft values with our TypeScript code. It's technical, but a great resource.
- [List and summary of commands (Unofficial Minecraft wiki)](https://minecraft.wiki/w/Commands#List_and_summary_of_commands): Most add-ons will run some commands. This community-supported wiki is the best resource for learning each and every command.
- [《基岩版附加包开发入门指南》](https://learn.microsoft.com/en-us/minecraft/creator/documents/gettingstarted)：手把手教你创建第一个资源包和行为包
- [《Molang语言入门指南》](https://learn.microsoft.com/en-us/minecraft/creator/documents/molangbeginnersguide)：掌握这个专为Minecraft设计的脚本语言
- [《GameTest框架入门》](https://learn.microsoft.com/en-us/minecraft/creator/documents/gametestgettingstarted)：使用JavaScript进行游戏测试的最佳实践
- [《TypeScript游戏开发指南》](https://learn.microsoft.com/en-us/minecraft/creator/documents/scriptinggettingstarted)：微软官方推荐的脚本开发方式
- [@minecraft/server模块文档](https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/mojang-minecraft/mojang-minecraft)：通过TypeScript操作游戏数据的核心API
- [《命令大全（非官方Wiki）》](https://minecraft.wiki/w/Commands#List_and_summary_of_commands)：社区维护的最新命令参考手册
## Sample Behavior & Resource Packs
## 示例资源包与行为包
These packs are maintained and published by Mojang.
**Mojang官方维护：**
- ⭐ [原版资源包模板](https://aka.ms/resourcepacktemplate)
- ⭐ [原版行为包模板](https://aka.ms/behaviorpacktemplate)
- [测试版资源包模板](https://aka.ms/MinecraftBetaResources)
- [测试版行为包模板](https://aka.ms/MinecraftBetaBehaviors)
- [历史版本存档](https://bedrock.dev/packs)
- ⭐ [Vanilla Resource Pack](https://aka.ms/resourcepacktemplate)
- ⭐ [Vanilla Behavior Pack](https://aka.ms/behaviorpacktemplate)
- [Vanilla Resource Pack (BETA)](https://aka.ms/MinecraftBetaResources)
- [Vanilla Behavior Pack (BETA)](https://aka.ms/MinecraftBetaBehaviors)
- [Pack Archive (old versions)](https://bedrock.dev/packs)
**开源社区项目：**
- [Wiki附加包](https://github.com/Bedrock-OSS/wiki-addon)
- [附魔详情显示](https://github.com/supercam19/EnchantmentDetails)
- [BC开发者工具包](https://github.com/BedrockCommands/developer-packs)
These packs are published by the open-source community
## 脚本开发资源
- [wiki-addon](https://github.com/Bedrock-OSS/wiki-addon)
- [Enchantment Details](https://github.com/supercam19/EnchantmentDetails)
- [BC developer-packs](https://github.com/BedrockCommands/developer-packs)
- [GameTests API封装库](https://github.com/notbeer/Framework-Wrapper)
- [插件API入门套件](https://github.com/MajestikButter/Plugin-API-Starter-Pack)
- [方块标签调试工具](https://mcpedl.com/debug-stick/)
## Scripting Resources
## 光线追踪资源
- ⭐ [光线追踪与PBR材质指南](https://docs.microsoft.com/en-us/minecraft/creator/documents/rtxgettingstarted)
- ⭐ [光线追踪常见问题解答](https://help.minecraft.net/hc/en-us/articles/4408865164173-Minecraft-with-Ray-Tracing-and-Advanced-Graphics-FAQ)
- [Reddit社区入门指南](https://www.reddit.com/r/minecraftRTX/comments/iq3lkl/getting_startedhelpful_guidesresource_packs/)
- [RenderBender渲染工具](https://github.com/SpeedyCodes/RenderBender)
- [RTX预设分享频道](https://discord.com/channels/691547840463241267/919021996271108108)
- [Substance 3D Painter插件](https://github.com/jasonjgardner/painter-plugin-texture-set-json)
- [GameTests API Wrapper](https://github.com/notbeer/Framework-Wrapper)
- [GameTests Plugin-API-Starter-Pack](https://github.com/MajestikButter/Plugin-API-Starter-Pack)
- [Useful for Block Tags](https://mcpedl.com/debug-stick/)
## 附加包发布平台
## Raytracing Resources
- ⭐ [Ray Tracing and PBR Texturing guide](https://docs.microsoft.com/en-us/minecraft/creator/documents/rtxgettingstarted)
- ⭐ [Minecraft with Ray Tracing and Advanced Graphics FAQ](https://help.minecraft.net/hc/en-us/articles/4408865164173-Minecraft-with-Ray-Tracing-and-Advanced-Graphics-FAQ)
- [r/minecraftRTX Getting Started Guide](https://www.reddit.com/r/minecraftRTX/comments/iq3lkl/getting_startedhelpful_guidesresource_packs/)
- [RenderBender](https://github.com/SpeedyCodes/RenderBender)
- [RTX Presets](https://discord.com/channels/691547840463241267/919021996271108108)
- [`.texture_set.json` Adobe Substance 3D Painter plugin](https://github.com/jasonjgardner/painter-plugin-texture-set-json)
- ⭐ [官方市场](https://www.minecraft.net/en-us/catalog)
- ⭐ [MCPEDL社区](http://mcpedl.com/?cookie_check=1)
- ⭐ [创作者招聘平台](https://www.bucketofcrabs.net/)
- [MCDLHub整合平台](https://mcdlhub.com/)
- [CubitosMC西班牙社区](https://www.cubitosmc.com/)
- [Modbay模组站](https://modbay.org/)
- [市场数据分析](https://mcmarketstats.miste.fr/globalStats/)
- [官方合作伙伴列表](https://www.playthismap.com/partners)
## Addon Marketplaces & Links
## 其他实用工具
- ⭐ [Minecraft Marketplace](https://www.minecraft.net/en-us/catalog)
- ⭐ [MCPEDL](http://mcpedl.com/?cookie_check=1)
- ⭐ [Bucket of Crabs (Marketplace joblist)](https://www.bucketofcrabs.net/)
- [MCDLHub](https://mcdlhub.com/)
- [CubitosMC](https://www.cubitosmc.com/)
- [Modbay](https://modbay.org/)
- [Minecraft Marketplace Stats](https://mcmarketstats.miste.fr/globalStats/)
- [Minecraft Marketplace Partners](https://www.playthismap.com/partners)
## Other useful Links
- [UUID v4 Generator (online)](https://www.uuidgenerator.net/version4)
- [Minecraft Marketplace partner Twitter list](https://twitter.com/i/lists/1191945551853629442?s=09)
- [Minecraft.net Official Add-ons page](https://www.minecraft.net/en-us/addons)
- [Run Bedrock on Linux](https://github.com/Element-0/ElementZero)
- [Linux Packaging Scripts](https://github.com/ChristopherHX/linux-packaging-scripts)
- [Block Models](https://blockmodels.com/)
- [Bedrock Addons Reddit](https://www.reddit.com/r/BedrockAddons/)
- [Windows 10 Non-renderdragon install](https://support.playhive.com/windows-10-installing-non-renderdragon-clients/)
- [Bedrock Edition Realm Protocol](https://github.com/NobUwU/BeRP)
- [Java & Bedrock Client](https://github.com/kennyvv/Alex)
- [Skin Pack Generator](https://github.com/MedicalJewel105/bedrock-skin-pack-generator)
- [UUID v4生成器（在线）](https://www.uuidgenerator.net/version4)
- [市场创作者Twitter列表](https://twitter.com/i/lists/1191945551853629442?s=09)
- [官方附加包页面](https://www.minecraft.net/en-us/addons)
- [Linux运行基岩版](https://github.com/Element-0/ElementZero)
- [Linux打包脚本](https://github.com/ChristopherHX/linux-packaging-scripts)
- [方块模型库](https://blockmodels.com/)
- [Reddit附加包社区](https://www.reddit.com/r/BedrockAddons/)
- [非RenderDragon客户端安装指南](https://support.playhive.com/windows-10-installing-non-renderdragon-clients/)
- [领域服务器协议](https://github.com/NobUwU/BeRP)
- [跨平台客户端](https://github.com/kennyvv/Alex)
- [皮肤包生成器](https://github.com/MedicalJewel105/bedrock-skin-pack-generator)

88
docs/wiki/meta/using-schemas.md
View File

@@ -1,5 +1,5 @@
---
title: Using Schemas
title: 使用Schema
mentions:
- SirLich
- MedicalJewel105
@@ -7,57 +7,63 @@ mentions:
- KalmeMarq
---
A JSON schema gives you two things: validation to be sure that your JSON has the correct structure and (depending on editor support) IntelliSense to help you write your JSON correctly, to begin with. Schemas are nice because they give you instant feedback when you screw something up, but they can't catch everything.
# 使用Schema
JSON schemas are just JSON files themselves and don't do anything on their own. You can write your own or use somebody else's. There's a handful of schemas for Bedrock out there already. Since none of the schemas are "official" (that I know of), and since Bedrock is a moving target, there will probably be some inaccuracies in any schema that you find. So keep that in mind: sometimes the issue will be in your code, sometimes the schema may be wrong. If you find a wrong schema, consider improving it and giving the author a pull request to our collective benefit.
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
To get the validation working, you'll need a validator. You have many options here, including editor-specific options.
JSON Schema能为您提供两大核心功能：**验证**确保JSON结构正确性，以及**智能感知**辅助编写（具体取决于编辑器支持）。Schema的优势在于能即时反馈错误，但需注意它无法捕捉所有潜在问题。
## Schemas
Schema本身也是JSON文件，需借助验证工具发挥作用。您可以使用现有Schema或自行编写。目前已有多个适用于Minecraft基岩版的Schema，但请注意这些Schema并非官方认证（据我所知），且基岩版持续更新迭代，因此任何现有Schema都可能存在不准确之处。请保持理性认知：问题可能出在您的代码，也可能是Schema本身存在缺陷。若发现Schema错误，建议贡献改进并向作者提交Pull Request，共同完善生态。
Many schemas exist, with many minor differences. Try out different schemas and see which one works best for you:
## Schema列表
| Author | Supports | Note |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [Assassin](https://github.com/aexer0e/bedrock-schema) | Behavior pack entity file | The original Schema this article was written for |
| [Tschrock's](https://github.com/bedrock-studio/bedrock-json-schemas/) | Manifest, Actor Animation Controller, Actor Animations, Actor Resource Definition, Render Controller, Geometry | |
| [stirante](https://github.com/stirante/bedrock-shader-schema/) | Shaders | |
| [KalmeMarq](https://github.com/KalmeMarq/Bugrock-JSON-UI-Schemas/) | JSON UI files (including _ui_defs.json and _global_variables.json) | |
现有多种Schema各具特色，建议尝试不同方案选择最适合您的：
## VSCode
| 作者 | 支持范围 | 备注 |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [Assassin](https://github.com/aexer0e/bedrock-schema) | 行为包实体文件 | 本文最初基于此Schema编写 |
| [Tschrock's](https://github.com/bedrock-studio/bedrock-json-schemas/) | 清单文件、实体动画控制器、实体动画、实体资源定义、渲染控制器、几何体 | |
| [stirante](https://github.com/stirante/bedrock-shader-schema/) | 着色器 | |
| [KalmeMarq](https://github.com/KalmeMarq/Bugrock-JSON-UI-Schemas/) | JSON UI文件（包含_ui_defs.json 和 _global_variables.json） | |
To use this schema inside your JSON file in VSCode, simply add this line to your root object:
## VSCode配置
### 单文件配置
在JSON文件根对象中添加以下字段即可启用Schema验证：
`"$schema": "https://aexer0e.github.io/bedrock-schema/"`
It should look like something like this:
完整示例：
<CodeHeader></CodeHeader>
```json
"format_version": "1.14.0",
"$schema": "https://aexer0e.github.io/bedrock-schema/"
```
### Adding Schema to Workspaces
If you want to utilize this schema to work with all of your files inside your Workspace, you can add it to your VS Code Workspace's settings.
To do this, make sure you're in your Workspace, then press `Ctrl+Shift+P` and type and select `>Preferences: Open Workspace Settings (JSON)`. After that, add this to the root object
<CodeHeader></CodeHeader>
```json
"settings": {
"json.schemas": [
{
"fileMatch": [
"*.json"
],
"url": "https://aexer0e.github.io/bedrock-schema/"
}
]
::: code-group
```json [示例]
{
"format_version": "1.14.0",
"$schema": "https://aexer0e.github.io/bedrock-schema/"
}
```
:::
To test if it works, create a `.json` file, open an object, and see if you get the auto-completion options. (You can also press `Ctrl+Space` to force it into showing the available options.)
### 工作区配置
若需为整个工作区启用Schema验证，请按以下步骤操作：
1. 在目标工作区中按下 `Ctrl+Shift+P`
2. 输入并选择 `>Preferences: Open Workspace Settings (JSON)`
3. 在根对象中添加以下配置：
::: code-group
```json [工作区设置]
{
"settings": {
"json.schemas": [
{
"fileMatch": ["*.json"],
"url": "https://aexer0e.github.io/bedrock-schema/"
}
]
}
}
```
:::
验证配置是否生效：新建`.json`文件，在对象中输入内容时观察是否出现自动补全提示（也可手动按`Ctrl+Space`触发提示）。

105
docs/wiki/meta/version-control.md
View File

@@ -1,89 +1,100 @@
---
title: Version Control
title: 版本控制
mentions:
- SirLich
- sermah
---
Version control is the concept of backing up your code iteratively, so you can roll back to specific versions as needed. Version control could be achieved at the most basic level by taking a `.zip` of your addon every day and uploading it to google drive. This isn't unreasonable, but it has three significant difficulties that proper VCS (version control systems) fix:
# 版本控制
- It isn't easy to compare versions
- It isn't easy to _actually_ roll-back to a previous version
- It doesn't do anything to help in team-collaboration
<!--@include: @/wiki/bedrock-wiki-mirror.md-->
This tutorial will teach the basics of a tool called `git`, and a free, online git storage service called `GitHub. Anyone may follow along, but you will receive the most benefit if you are working in a team environment or often lose your work because you forget to back up.
版本控制的核心概念是定期备份代码迭代版本，以便在需要时回滚到特定版本。最基本的版本控制可以通过每天将附加包打包成`.zip`并上传到谷歌网盘实现。这并非不合理，但存在三个显著缺陷，而专业的版本控制系统（VCS）能够有效解决：
This tutorial will not be focusing directly on teaching `git` or `GitHub`, as outside knowledge sources better do this. The focus will be on setting up these tools for Minecraft once the basics have been learned.
- 版本差异比对困难
- 实际回滚到旧版本操作繁琐
- 对团队协作毫无帮助
本教程将介绍`git`工具的基本使用方法，以及免费的在线git托管服务`GitHub`。任何人都可以跟随学习，但如果您身处团队协作环境或经常因忘记备份而丢失工作成果，将会获得最大收益。
本教程不会直接教授`git`或`GitHub`的基础操作，因为这些知识已有优质外部资源可供学习。重点将放在掌握基础后如何针对Minecraft项目进行工具配置。
## Git
`git` is a tool installed locally on your machine and allows you to version your files. You can `commit` changes to your files with a small message (ex. "Fixed issue where dragons couldn't fly after being tamed"), view the full change-list, and quickly jump back to specific changes.
`git`是安装在本地计算机上的版本管理工具，可对文件进行版本控制。您可以通过简短信息（例如"修复驯服后龙无法飞行的BUG"）提交（`commit`）文件变更，查看完整修改记录，并快速回滚到特定版本。
Git is insanely powerful and the de-facto tool for all major programming projects. The most significant drawback for MC work is that it is _complicated_. Be patient while learning.
Git功能强大且是主流编程项目的标配工具。其应用于Minecraft开发的主要缺点是学习曲线陡峭。请保持耐心循序渐进。
For a complete walkthrough of `git`, you should follow the following [git tutorial.](https://www.atlassian.com/git/tutorials/what-is-git)
完整的`git`学习请参考[git官方教程](https://www.atlassian.com/git/tutorials/what-is-git)。
## GitHub
GitHub is a version of your git project (`repository`) that is hosted online. This allows multiple people to work on the same project at the same time and collaborate. This is very helpful for map-making. By hosting on Github, you can also (optionally) make your code public, making it easier than ever to share your addons with the world.
GitHub是git项目（`repository`仓库）的在线托管平台，允许多人同时协作开发。这对于地图制作尤为实用。通过GitHub托管，您还可以选择将代码公开，更方便地向世界分享您的附加包。
For a complete walkthrough of using `Github`, you should follow this [github tutorial](https://guides.github.com/activities/hello-world/).
完整的GitHub学习请参考[GitHub入门指南](https://guides.github.com/activities/hello-world/)。
## Vocabulary Quiz
## 术语自测
If you've gotten this far, hopefully, you have a GitHub account and are familiar with `git` in a small way. The following terms will be used in this tutorial. If you don't know them, please google :)
如果您已学习至此，希望您已注册GitHub账号并对`git`有初步了解。以下术语将在教程中使用，若不熟悉请自行查询：
- repository
- branch
- commit
- github
- git
- repository（仓库）
- branch（分支）
- commit（提交）
- github
- git
# Setting up Git
# Git环境配置
This assumes you are adding an _existing_ project to git. The steps are similar if you are starting from scratch.
本节假设您要将已有项目加入git管理。新建项目的操作流程类似。
## Structure
## 目录结构
The big issue with using `git` for addons is that `git` generally works by encapsulating a _single_ folder and managing it. Of course, in Bedrock Addons, assets are spread across two folders: The `BP`, and `RP`. To get around this issue, we will place our repository outside of the `com.mojang` folder entirely and then use window `junctions` to "copy" the folders in.
在附加包开发中使用`git`的主要问题在于：git通常通过管理单个文件夹实现版本控制，而基岩版附加包资源分散在`BP`和`RP`两个文件夹。为解决此问题，我们将仓库完全置于`com.mojang`文件夹之外，使用Windows符号链接（`junctions`）实现文件夹映射。
There are many advantages of placing our project in a separate location:
将项目置于独立位置有以下优势：
- We can include additional files as needed, such as config files, tools, notes, .bb files, etc
- We can combine the RP and the BP into one repository
- All of our projects can be easily viewed in a simple location, instead of nested deep within com.mojang
- 可自由添加配置文件、工具、笔记、.bb文件等附加内容
- 可将RP和BP整合至同一仓库
- 所有项目可在统一位置查看，避免深埋于com.mojang目录中
## Creating a Git Repository
## 创建Git仓库
Pick a convenient location for your projects. I placed mine at `C:/sirlich/projects`. Make a new folder with the name of your map. We will be using `wiki` as the name of our mock project.
为项目选择合适的位置。示例使用`C:/sirlich/projects`。新建以项目命名的文件夹，示例项目名为`wiki`。
Right-click the folder, and click `"Open git Bash"`. If this option doesn't appear, you can open `git bash` from the start menu and navigate your project folder. If you don't have `git bash` installed, you should do so now.
右键点击文件夹选择`"Open git Bash"`。若未显示此选项，可通过开始菜单打开`git bash`并导航至项目目录。若未安装`git bash`请立即安装。
Type: `git init`. This will create a blank repository in your project.
输入命令：`git init`。这将在项目中创建空白仓库。
## Linking your existing RP and BP
## 链接现有RP和BP
The next step is to make the repository aware of your RP and BP folders. We will be using window symlink "junctions". When we create a junction, we essentially create a wormhole in our file system that will make it appear like your files are in two places at once. Deleting/editing/adding files is perfectly copied over.
接下来通过创建Windows符号链接让仓库识别您的RP和BP文件夹。符号链接相当于文件系统的虫洞，使文件看似同时存在于两个位置。删除/编辑/添加操作会实时同步。
Type: `mklink /J wiki_RP "C:/path/to/RP/in/com/mojang"`
Type: `mklink /J wiki_BP "C:/path/to/BP/in/com/mojang"`
输入命令：
`mklink /J wiki_RP "C:/path/to/RP/in/com/mojang"`
`mklink /J wiki_BP "C:/path/to/BP/in/com/mojang"`
When you are finished, you should see `wiki_RP` and `wiki_BP` in your project folder, containing all your assets, existing files, etc.
完成后，项目文件夹中将出现`wiki_RP`和`wiki_BP`目录，包含所有现有资源文件。
You can now push this repository to `github`, following the tutorial above.
此时可按照前述教程将仓库推送至`github`。
## Extra Files
## 附加文件
Because we created our repository based on symlinks, we can add anything we like into the project folder without worrying about breaking the com.mojang folder. I like to track `.bb` files, cover-art files (`.kra` etc.).
由于我们通过符号链接创建仓库，可在项目文件夹中添加任意文件而不影响com.mojang目录。推荐追踪`.bb`文件、封面设计文件（如`.kra`格式）等。
You can also add notes, video files, or anything else you want to track.
您还可以添加笔记、视频文件等需要版本控制的任何内容。
## Working with your VCS
## VCS使用规范
The main things to remember about working with VCS:
使用版本控制系统需牢记以下要点：
- Always `pull` before starting work
- Commit and `push` often
- Always `push` before stopping work
- If you screw up your files super bad, you can always reset to the last working version. If you commit/push often, hopefully, this wasn't too long ago.
- Always, and I mean `always` make good commit messages. It's vital when you have to roll back.
- 开始工作前务必先`pull`拉取最新版本
- 频繁`commit`提交并`push`推送
- 结束工作前必须`push`推送更改
- 若文件严重损坏，可随时重置到最近可用版本。经常提交/推送能最大限度减少损失
- 必须（强调）编写规范的提交信息，这在需要回滚时至关重要
::: code-group
```json [示例符号链接]
mklink /J demo_RP "C:/Users/Steve/AppData/Local/Packages/Microsoft.MinecraftUWP_8wekyb3d8bbwe/LocalState/games/com.mojang/development_resource_packs/demoRP"
```
:::