bridge.进阶功能¶
bridge.的进阶能力主要围绕项目配置、Dash编译器和扩展系统展开。它们能让一个附加包项目拥有更强的创建、补全、转换和打包能力，但多数功能只在bridge.项目内生效。发布给Minecraft前，必须经过Dash或相应导出流程转换为游戏能够读取的普通文件。
区分工具语法和游戏语法
Dash自定义命令、Dash自定义组件、.molang文件和生成器脚本不是Minecraft原生API。它们不能直接复制到游戏世界中使用，也不能作为其他编辑器一定能识别的标准格式。
项目配置¶
bridge.项目根目录中的config.json保存工具层项目配置。它遵循Bedrock OSS组织提出的项目配置标准，主要告诉bridge.项目名称、作者、命名空间、目标版本、实验性玩法开关和各类包的位置。
常见字段包括：
| 字段 | 用途 |
|---|---|
type | 指定项目类型，基岩版项目通常为minecraftBedrock。 |
name和description | 指定项目在bridge.界面和相关工具中显示的名称与描述。 |
authors | 记录作者名称，也可以为作者附加图标路径。 |
namespace | 指定项目默认命名空间，用于生成标识符和提供补全。 |
targetVersion | 指定开发目标Minecraft版本，影响可创建文件、补全和校验。 |
experimentalGameplay | 记录实验性玩法开关，bridge.会据此筛选可用功能。 |
packs | 把behaviorPack、resourcePack、skinPack和worldTemplate等包类型映射到项目内路径。 |
worlds | 通过glob模式记录项目内世界文件夹。 |
packDefinitions | 为工具补充难以自动缓存的项目定义，例如记分板名称或额外标签。 |
bdsProject | 标记项目是否面向BDS，以便显示相关脚本模块。 |
compiler | 配置Dash默认构建配置；设为false可以禁用Dash。 |
如果项目从Local Project转换而来，或从.mcaddon、.mcpack导入而来，建议先检查packs、namespace和targetVersion是否符合真实项目结构。
Dash编译器¶
Dash是bridge.内置的项目编译器。它负责把项目源文件转换为开发输出或发布输出，并为自定义命令、自定义组件、.molang文件、生成器脚本和格式版本修正等功能提供转换流程。
日常开发中，内置Dash通常以监视模式运行：保存源文件后，受影响文件会重新编译到输出目录。如果已经设置com.mojang同步，开发输出会直接进入Minecraft开发包目录。导出项目时，bridge.会使用Dash生成生产构建，再写入.mcaddon、.mcworld或.mctemplate。
Dash的构建配置由插件数组组成。插件顺序会影响转换结果，数组中越靠前的插件越早运行。文档列出的内置插件包括：
typeScript：把TypeScript转译为JavaScript。customEntityComponents、customItemComponents和customBlockComponents：处理Dash自定义组件。customCommands：处理Dash自定义命令。molang：处理.molang文件并可压缩Molang表达式。generatorScripts：启用生成器脚本。formatVersionCorrection：修正部分JSON文件的格式版本处理。simpleRewrite：把开发输出写入目标目录。rewriteForPackaging：为打包格式重写输出文件。
熟悉终端的用户还可以使用独立Dash。文档将独立Dash描述为基于Deno的命令行构建，适合需要脱离bridge.界面进行自动化构建的项目。
除了项目配置里的默认compiler字段，Dash还支持在项目的.bridge/compiler/目录中增加额外构建配置文件。每个配置都可以声明自己的name、icon、description和plugins数组，用于区分“开发输出”“发布输出”“压缩构建”等不同目标。和默认配置一样，plugins的顺序会直接决定执行顺序。
自定义命令¶
Dash自定义命令存放在行为包的commands/文件夹中，每个JavaScript或TypeScript文件导出一个命令定义。命令定义通常包含三个部分：
name指定在bridge.补全列表中出现的命令名。schema描述命令参数，供补全和校验使用。template根据用户输入的参数生成一个或多个普通Minecraft命令。
自定义命令会出现在.mcfunction和部分JSON命令位置的补全中。编译后，Dash会把它们展开为普通命令。因此，自定义命令不能直接在游戏聊天栏或命令方块中输入。
在底层实现上，bridge.还维护了一套自己的命令架构，用来做命令校验和自动补全。文档列出的基础类型包括command、string、number、boolean、selector、molang、blockState、jsonData、scoreData、coordinate、subcommand和integerRange，并允许通过$customTypes把一组参数结构抽成可复用的自定义类型。换句话说，Dash自定义命令补全依赖的是bridge.内部工具架构，不是Minecraft公开发布的命令定义格式。
自定义组件¶
Dash自定义组件用于把实体、方块和物品文件中的重复JSON逻辑抽成可复用组件。组件文件按类型分别放在行为包的components/entity/、components/block/和components/item/文件夹中。
一个组件定义通常包含：
name：组件名，建议使用项目命名空间。schema：组件属性的JSON架构，用于补全和校验。template：把组件属性转换为实际要合并到文件中的JSON。
例如，项目可以把一组固定生命值、碰撞箱和事件响应封装成组件，再在多个实体文件中使用。编译后，最终输出仍应是Minecraft能够读取的普通实体、方块或物品JSON。
.molang文件¶
bridge.允许把常用Molang逻辑放进专门的.molang文件。molang编译插件会从BP/molang/和RP/molang/读取这些文件，并在项目中提供可复用函数。
.molang文件可以定义函数。调用时可使用f.<函数名>(...)或function.<函数名>(...)。文档示例中，函数参数通过a.<参数名>或arg.<参数名>访问，临时变量会自动限定在当前函数体内。
适合封装重复表达式
如果同一段Molang条件反复出现在动画控制器、客户端实体或物品文件中，可以考虑把它移入.molang文件。这样更容易统一修改，但也意味着项目必须经过Dash编译后才能发布。
生成器脚本¶
生成器脚本是放在项目内的JavaScript或TypeScript文件，用于生成JSON、.mcfunction或其他文件。使用它之前，需要在Dash配置中启用generatorScripts插件。
简单生成器可以直接默认导出要写入的对象或字符串。复杂生成器可以使用@bridge/generate模块：
useTemplate读取一个模板文件，并可选择不把模板输出到构建结果。createCollection创建文件合集，让一个脚本生成多个文件。
生成器脚本适合生成大量规则相似的文件。例如，按照同一模板批量生成物品定义、函数文件或本地化条目。
扩展系统¶
bridge.扩展可以全局安装，也可以安装到项目的.bridge/extensions文件夹中。全局扩展可用于所有项目，本地扩展只对当前项目生效，更适合团队项目随源码一起管理。
每个扩展都需要清单文件。清单通常包含name、description、author、version、id、tags和target等字段。扩展可以提供多种能力：
| 能力 | 说明 |
|---|---|
| 预设 | 在新建文件窗口中提供表单化文件创建流程。 |
| 代码片段 | 在文本编辑器或树编辑器中快速插入JSON或文本。 |
| 主题 | 修改bridge.界面、语法高亮和编辑器配色。 |
| 编译器插件 | 扩展Dash构建流程。 |
| 脚本模块 | 通过@bridge/*模块访问文件系统、标签页、通知、窗口和项目数据。 |
| iframe API | 把外部网页工具嵌入bridge.标签页，并通过通信通道访问部分bridge.的API。 |
官方若干脚本模块页面仍包含TODO或未完成说明。实际编写扩展时，建议同时查看bridge.源码和官方扩展仓库中的示例。
如果你准备正式写扩展，建议继续阅读bridge.脚本模块和bridge.iframe API。前者适合直接在扩展里写界面和逻辑，后者适合把现成网页工具嵌进bridge.。
预设与代码片段¶
预设用于从表单创建一组文件。一个预设通常位于扩展的presets/目录中，并包含自己的manifest.json。预设清单可以声明名称、图标、分类、启用条件、输入字段、要创建的文件和要扩展的文件。复杂预设还可以通过预设脚本处理文件输入、开关、选择器和批量生成逻辑。
代码片段则更轻量。片段JSON通常声明name、description、fileTypes、locations和data。fileTypes使用bridge.文件类型ID，locations使用JSON路径glob模式，决定片段能插入到哪些文件位置。
何时谨慎使用¶
如果项目必须能被任意代码编辑器直接维护，或者发布前不希望依赖专门构建流程，就应减少Dash自定义语法的使用。相反，如果团队统一使用bridge.，并且项目已经使用版本管理和固定构建配置，Dash和扩展系统可以显著减少重复工作。
扩展开发入门¶
如果要创建bridge.扩展，每个扩展需要一个清单文件（extension.json或manifest.json），其中必须包含：
name：扩展名称，显示在扩展商店中description：详细描述，显示在扩展商店中author：作者名称version：版本号，格式为主版本.次版本.修订版本id：唯一标识符，通常为作者名-扩展名的格式
发布扩展¶
完成的扩展可以提交到bridge.官方扩展仓库，通过审核后会出现在bridge.的扩展商店中供所有用户下载。
扩展的三个关键能力¶
1. 预设（Presets）¶
预设是bridge.中最常见的扩展功能。一个预设通常： - 位于扩展的presets/目录中 - 包含自己的清单，声明名称、图标、分类等 - 提供表单化的输入字段供用户填写 - 根据用户输入生成一组完整的文件（例如整个实体定义） - 支持复杂逻辑，如条件字段、动态列表、跳过某些字段等
2. 代码片段（Snippets）¶
代码片段是轻量级的快捷插入功能。片段定义包含： - name和description：片段名称和描述 - fileTypes：支持的文件类型ID（如json、mcfunction等） - locations：能插入的JSON路径（使用glob模式） - data：要插入的内容
3. 脚本模块（Script Modules）¶
高级扩展可以使用@bridge/*模块访问bridge.的功能： - @bridge/env：环境信息 - @bridge/fs：文件系统读写 - @bridge/project：当前项目数据 - @bridge/tab：标签页管理 - @bridge/notifications：发送通知 - @bridge/windows：弹出窗口 - @bridge/command-bar：命令栏集成
查看示例和获取帮助¶
bridge.官方维护了一个活跃的示例扩展仓库。在开发自己的扩展时，查看这些源代码是学习各种扩展能力的最好方式。
bridge.社区的Discord服务器（https://discord.gg/uj8K2S9）有专门的#扩展开发频道，可以在那里提问和讨论开发问题。
官方扩展开发API文档¶
bridge.文档详细介绍了以下API模块和系统：
脚本模块API¶
@bridge/project- 项目访问和编译控制@bridge/fs- 文件系统操作@bridge/env- 环境信息@bridge/tab- 标签页管理@bridge/sidebar- 侧边栏操作@bridge/windows- 窗口管理@bridge/ui- UI组件和交互@bridge/notifications- 通知系统@bridge/command-bar- 命令栏集成@bridge/json5- JSON5解析@bridge/import- 模块导入- 其他工具模块
扩展系统¶
- 扩展清单格式和配置选项
- iframe API - 嵌入外部网页工具
- 编译器插件系统
提示：详细的API文档请查阅bridge.文档，这些API属于bridge.工具特定的扩展系统，与基岩版游戏API不同。