Skip to content
cmdcorp6534Public

About

一个关于鞘翅飞行的 Minecraft 基岩版 Addon

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

天空即为极限 · MCBE-Air

一个面向 Minecraft 基岩版的鞘翅飞行辅助 Addon。使用命令获取“飞行面板”后,可以快速获得鞘翅/烟花、设置航点并开启自动驾驶。

Package mcpack

仅支持 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/server 2.10.0。
  • 需要启用行为包;本包不包含资源包。

安装

  1. 从 Releases 下载最新的 .mcpack。
  2. 双击文件,或用 Minecraft 打开,等待行为包导入。
  3. 进入世界设置 → 行为包,激活“天空即为极限”。
  4. 进入世界即可使用。

开发时先运行 npm ci && npm run build 生成 scripts/main.js,再把本目录放进 development_behavior_packs 下测试。

快速开始

1. 获取飞行面板

执行:

/cmdcorp_air:airstick

获得名为“飞行面板”的木棍,物品栏已满时不会给予。

  • 第一次使用(尚无面板数据)时,右键初始化,ActionBar 出现菜单。
  • 之后每次右键:切换到下一个选项,并重置 3 秒倒计时。
  • 停止右键 60 ticks后,当前选项才会执行;继续右键会切到下一项。

面板状态按玩家独立保存在动态属性中,重进世界仍会保留,直到选择“关闭并重置”。

面板木棍现在可以正常移动或丢弃;丢失后重新执行 /cmdcorp_air:airstick 即可。

2. 设置航点

先初始化面板,然后执行:

/cmdcorp_air:wpt <x> <z>

例如:

/cmdcorp_air:wpt 1000 -200
  • x、z 是绝对坐标,支持小数。
  • 只设置水平航点,不设置高度。
  • 如果面板尚未初始化,命令会返回 SystemNotStartedError。

3. 开启自动驾驶

  1. 装备鞘翅;
  2. 使用鞘翅飞行;
  3. 确认高度不低于 30 格、距离航点超过 50 格;
  4. 用面板选择“自动驾驶”,停止右键等待 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 格范围内后会自动断开,请自行控制落地。

注意与警告(GPWS)

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 不会自动恢复接通,需要手动重新选择“自动驾驶”;如果仍存在其他禁用条件,则继续显示对应原因。

飞行 HUD

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 参数中加入该模块。

把游戏报错定位回 TypeScript

游戏终端里的报错只会显示编译后的位置,例如:

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

鸣谢

  1. 本项目灵感来源于纪录片《空中浩劫》,原名 Air Crash Investigation 或 Mayday 。
  2. 本项目少部分内容为人工智能 DeepSeek 编写。

声明

此 README 由人工智能生成,不保证与实际情况完全相符,具体情况请进入游戏体验。

本项目与 Mojang Studios 或 Microsoft 没有隶属、赞助或认可关系。Minecraft 是 Mojang Synergies AB 的商标。

About

一个关于鞘翅飞行的 Minecraft 基岩版 Addon

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages