一个面向 Minecraft 基岩版的鞘翅飞行辅助 Addon。使用命令获取“飞行面板”后,可以快速获得鞘翅/烟花、设置航点并开启自动驾驶。
仅支持 Minecraft 基岩版(Behavior Pack),不适用于 Java 版。
- 飞行面板:使用
/cmdcorp_air:airstick获取“飞行面板”木棍,右键打开/操作菜单。 - 快速补给:一键获得鞘翅,或 64 个飞行时间 3 的烟花火箭。
- 航点自动驾驶:用命令设置水平航点,自动驾驶会持续把朝向修正到航点方向。
- 飞行安全检查:自动检查鞘翅耐久、滑翔状态、高度、下降率和与航点的距离,不满足时自动断开。
- EGPWS 注意与警告:HUD 下方显示
PULL UP、STALL、SINK RATE、TERRAIN AHEAD、TERRAIN、ELYTRA DAMAGE等警告;包含前向地形检测与鞘翅耐久监控。 - 飞行 HUD:ActionBar 显示速度、水平速度、垂直速度、高度、俯仰/偏航和鞘翅耐久。
- Minecraft Bedrock 1.21.90 及以上,且游戏版本需要支持
@minecraft/server2.10.0。 - 需要启用行为包;本包不包含资源包。
- 从 Releases 下载最新的
.mcpack。 - 双击文件,或用 Minecraft 打开,等待行为包导入。
- 进入世界设置 → 行为包,激活“天空即为极限”。
- 进入世界即可使用。
开发时先运行 npm ci && npm run build 生成 scripts/main.js,再把本目录放进 development_behavior_packs 下测试。
执行:
/cmdcorp_air:airstick
获得名为“飞行面板”的木棍,物品栏已满时不会给予。
- 第一次使用(尚无面板数据)时,右键初始化,ActionBar 出现菜单。
- 之后每次右键:切换到下一个选项,并重置 3 秒倒计时。
- 停止右键 60 ticks后,当前选项才会执行;继续右键会切到下一项。
面板状态按玩家独立保存在动态属性中,重进世界仍会保留,直到选择“关闭并重置”。
面板木棍现在可以正常移动或丢弃;丢失后重新执行
/cmdcorp_air:airstick即可。
先初始化面板,然后执行:
/cmdcorp_air:wpt <x> <z>
例如:
/cmdcorp_air:wpt 1000 -200
x、z是绝对坐标,支持小数。- 只设置水平航点,不设置高度。
- 如果面板尚未初始化,命令会返回
SystemNotStartedError。
- 装备鞘翅;
- 使用鞘翅飞行;
- 确认高度不低于 30 格、距离航点超过 50 格;
- 用面板选择“自动驾驶”,停止右键等待 3 秒。
自动驾驶开启后会持续把朝向修正到航点方向。它只修正水平朝向(Yaw),不会自动控制俯仰和高度,飞行高度仍需要自己用视角或烟花维持。
| 选项 | 作用 |
|---|---|
| 自动驾驶 | 切换自动驾驶开关;条件不满足时不会开启,并在 HUD 显示原因 |
| 获得鞘翅 | 获得 1 个鞘翅 |
| 获得烟花火箭 | 获得 64 个飞行时间 3 的烟花火箭 |
| 关闭并重置 | 清除航点、自动驾驶状态和面板数据 |
选择“关闭并重置”后需要停手等待 3 秒,倒计时结束才会真正重置。
自动驾驶开启后,每 tick 都会重新检查以下条件;任意一项失效都会自动断开:
| 条件 | 要求 | 不满足时的提示 |
|---|---|---|
| 鞘翅 | 胸甲槽装备鞘翅,且耐久损耗低于 80% | GPWS ELYTRA DAMAGE |
| 航点 | 已用 /cmdcorp_air:wpt 设置航点 |
未定义航点 |
| 滑翔 | 正在使用鞘翅滑翔 | 未处于滑行状态 |
| 高度 | 相对下方方块/液面至少 30 格;低于时触发 GPWS TERRAIN 系列 |
GPWS |
| 下降率 | 垂直速度不低于 -0.8;超过时触发 GPWS SINK RATE / PULL UP |
GPWS |
| 距离 | 距航点大于 50 格 | 已在航点附近 |
自动驾驶不会自动降落。进入航点 50 格范围内后会自动断开,请自行控制落地。
HUD 最下方有一栏“注意与警告”。正常飞行时该栏为空;触发 Caution 或 Alert 时显示对应英文警告:
| 警告 | 类型 | 触发条件 |
|---|---|---|
PULL UP |
Alert(粗体红色) | 低高度下降且前向检测到地形(高度 < 50、下降 > 0.5 格/刻),或前方侧面障碍距离 < 40 格且撞击速度足以造成动能伤害 |
STALL |
Alert(粗体红色) | 非爬升、非接地阶段,仰角超过 60°(Pitch < -60);高空也会报告 |
SINK RATE |
Caution(粗体黄色) | 非爬升、非接地阶段,下降速度超过 0.8 格/刻(16 m/s),且没有 PULL UP |
TERRAIN AHEAD |
Caution(粗体黄色) | 前向检测到 60 格内的侧面地形/障碍,且(撞击速度足以造成动能伤害,或高度 > 3 格、撞墙后可能进入自由落体造成摔落伤害),并且没有 PULL UP |
TERRAIN |
Caution(粗体黄色) | 非爬升、非接地阶段,高度低于 30 格,垂直速度达到 0.5 格/刻(10 m/s,可能产生摔落伤害),且没有 PULL UP、也不是前向地形警告 |
ELYTRA DAMAGE |
Caution(粗体黄色) | 鞘翅耐久损耗达到 80%(AP_ETR_DAMAGE_MAX) |
补充规则:
- 爬升阶段(
VerticalSpeed > 0)不报STALL、SINK RATE、TERRAIN和低高度PULL UP,但前向侧面障碍仍然会触发TERRAIN AHEAD/PULL UP,避免起飞时撞墙; - 高度低于 30 格且下降速度小于 0.2 格/刻(4 m/s)时,视为最后进近/接地阶段,地面类警告静默,但前向侧面障碍仍然生效;
PULL UP显示时,不再同时显示SINK RATE、TERRAIN AHEAD和TERRAIN;PULL UP与STALL不会同时出现,STALL 优先级更高;ELYTRA DAMAGE是持续警告,不受起飞/接地静默影响;- 前向检测沿玩家速度方向、从头部发射,最大 80 格;只有命中方块侧面才算
TERRAIN AHEAD障碍,顶面/底面会被忽略,所以竖直俯冲时不会把地面误报成TERRAIN AHEAD; - 低高度
PULL UP仍可用任意前向地形确认,减少在虚空/开阔空域中的误报; - 根据 Wiki 的摔落伤害规则,垂直速度小于 0.5 格/刻(10 m/s)时下落高度会重置,通常不会摔伤,因此
TERRAIN只在垂直速度达到 0.5 格/刻时显示; - 根据 Wiki 的动能伤害公式,水平撞击速度不大于 0.3 格/刻(6 m/s)时不会造成动能伤害;但高空低速撞墙仍可能停止滑翔并转入自由落体,因此
TERRAIN AHEAD在这种情况下仍会保留; - 根据 Wiki 的摔落伤害规则,高度超过 3 格时自由落体可能造成摔落伤害,所以低速撞墙后仍有后续摔伤风险;
- 警报合并为一行,Alert 在前、Caution 在后,例如
STALL SINK RATE。
速度单位说明:Script API 的
getVelocity()返回格/游戏刻(block/tick),Wiki 通常使用米/秒;换算为 1 格/刻 = 20 格/秒。0.5 格/刻 ≈ 10 m/s,0.8 格/刻 = 16 m/s,1.0 格/刻 ≈ 20 m/s。
自动驾驶处于接通状态时,任意 Caution/Alert 都会断开 AP,禁用原因显示为 GPWS。警告解除后 AP 不会自动恢复接通,需要手动重新选择“自动驾驶”;如果仍存在其他禁用条件,则继续显示对应原因。
ActionBar 会显示:
- 当前选项和倒计时;
- 航点坐标、自动驾驶状态或禁用原因;
Speed:总速度;GroundSpeed:水平速度;VerticalVelocity:垂直速度;Altitude:相对下方方块/液面的高度;Pitch/Yaw:俯仰角和偏航角;ElytraDamage:鞘翅耐久损耗百分比;- “注意与警告”:GPWS Caution/Alert。
当 GPWS 发出警告时,仪表区内相关参数名称会变红:
Altitude:PULL UP、TERRAIN AHEAD、TERRAIN;VerticalVelocity:SINK RATE、TERRAIN,或由下降率触发的PULL UP;Pitch:STALL;ElytraDamage:ELYTRA DAMAGE。
参数集中在 src/config.ts:
| 参数 | 默认值 | 说明 |
|---|---|---|
CHOICE_REMAIN_TICKS |
60 |
菜单倒计时,60 tick = 3 秒 |
AP_ALT_REQUIREMENT |
30 |
自动驾驶最低高度 / GPWS TERRAIN 阈值 |
AP_SINK_RATE_MAX |
0.8 |
允许的最大下降速度 / GPWS SINK RATE 阈值 |
GPWS_PULL_UP_ALT |
50 |
PULL UP 高度阈值 |
GPWS_PULL_UP_SINK |
0.5 |
PULL UP 下降速度阈值(格/刻,≈10 m/s) |
GPWS_STALL_PITCH |
60 |
STALL 仰角阈值(度) |
GPWS_LANDING_ALT |
30 |
进近/接地阶段高度阈值 |
GPWS_LANDING_SINK |
0.2 |
进近/接地阶段下降速度阈值(格/刻,4 m/s) |
GPWS_FORWARD_DIST |
80 |
前向检测最大距离(格) |
GPWS_FORWARD_CAUTION |
60 |
TERRAIN AHEAD 警戒距离(格) |
GPWS_FORWARD_ALERT |
40 |
触发 PULL UP 的前向障碍距离(格) |
GPWS_FALL_DAMAGE_SINK |
0.5 |
可能造成摔落伤害的垂直速度阈值(格/刻,10 m/s) |
GPWS_FALL_DAMAGE_ALT |
3 |
自由落体可能造成摔落伤害的高度阈值(格) |
GPWS_KINETIC_DAMAGE_SPEED |
0.3 |
可能造成动能伤害的水平撞击速度阈值(格/刻,6 m/s) |
AP_ETR_DAMAGE_MAX |
80 |
鞘翅耐久损耗达到该百分比时触发 ELYTRA DAMAGE |
AP_DISTANCE_REQUIREMENT |
50 |
小于等于该距离时视为到达航点附近 |
FW_DATA |
3 |
发放的烟花飞行时间,范围 1–3 |
修改这些值后,需要重新运行 npm run build 生成 scripts/main.js。
src/是 TypeScript 源码;scripts/main.js是构建产物,也是manifest.json的入口。scripts/已加入.gitignore,不提交到仓库;本地构建或 Release workflow 会生成它。- 构建依赖记录在
package.json和package-lock.json中;需要 Node.js 18+。 - 首次安装依赖:
npm ci- 类型检查:
npm run check- 单次构建(类型检查 + esbuild 打包):
npm run build- 开发监听:
npm run watch- 如果需要同时监听类型错误,另开一个终端运行:
npm run check:watch构建使用 tsc --noEmit 做类型检查,再由 esbuild 将 src/main.ts 打包为 scripts/main.js。@minecraft/server 作为游戏原生模块保持 external,不打包;@minecraft/math 和 @minecraft/vanilla-data 一起打包进 scripts/main.js。esbuild 配置集中在 esbuild.config.mjs。
当前未使用 @minecraft/server-ui。以后需要引入时,请同时在 package.json 的 devDependencies、manifest.json 的 dependencies 和 esbuild 的 external 参数中加入该模块。
游戏终端里的报错只会显示编译后的位置,例如:
main.js:123:45
生产构建默认不包含 source map。需要调试时,先生成带 inline source map 的调试包:
npm run build:debug或者持续监听:
npm run watch:debug然后在项目根目录执行:
npm run map:error -- 123 45会输出类似:
src/utils.ts:67:12
其中 123 是 main.js 的行号,45 是列号;工具按 Minecraft 常见的 1-based 列号处理。调试结束后重新运行:
npm run build恢复不带 source map 的生产包。scripts/main.js 已被 .gitignore 忽略,不要提交调试版本。
node_modules/ 和 scripts/ 都已加入 .gitignore,不要提交。发布 workflow 会在构建后自行生成 scripts/main.js。
GitHub Actions 的打包流程见 .github/workflows/package.yml:
- push
v*tag:构建.mcpack并上传到对应的 GitHub Release; - tag 必须指向
main历史中的提交;workflow 会检查 tag 是否是origin/main的祖先,不是则直接失败; - 手动触发 workflow:构建所选 ref 的
.mcpack并上传为 Actions artifact,不创建 Release; - Workflow 会执行
npm ci和npm run build,不再依赖仓库中提交的scripts/main.js; - 打包时使用显式白名单,只允许
manifest.json、README.md、LICENSE、THIRD_PARTY_NOTICES.md和 manifest 指定的脚本入口;出现其他文件会直接失败; - 打包内容只包含上述文件(当前脚本入口为
scripts/main.js);scripts/下的其他文件、src/、node_modules/、package*.json等不会进入 mcpack。
发版时先合并到 main,再从 main 创建 tag:
git switch main
git pull --ff-only origin main
git tag v1.0.0
git push origin v1.0.0遇到问题或想提建议,欢迎在 Issues 反馈。
Copyright (C) 2026 cmdcorp6534
本项目使用 GNU Affero General Public License v3.0(AGPL-3.0-only)。
项目中使用的 Mojang AB 软件包(@minecraft/server、@minecraft/vanilla-data、@minecraft/math)按其 MIT License 授权。MIT 版权声明和许可文本已收录在 THIRD_PARTY_NOTICES.md,并随 .mcpack 一起分发。
对应源码:
https://github.com/cmdcorp6534/MCBE-Air
- 本项目灵感来源于纪录片《空中浩劫》,原名 Air Crash Investigation 或 Mayday 。
- 本项目少部分内容为人工智能 DeepSeek 编写。
此 README 由人工智能生成,不保证与实际情况完全相符,具体情况请进入游戏体验。
本项目与 Mojang Studios 或 Microsoft 没有隶属、赞助或认可关系。Minecraft 是 Mojang Synergies AB 的商标。