deathstar

Stellar Abyss 是一款面向桌面端、在浏览器中运行的 3D 太空战斗原型，使用 Babylon.js、TypeScript 和 Vite 构建。飞船、环境、宇宙和音频均采用原创且程序化生成——README 明确指出该项目未使用来自现有特许经营权的受保护飞船、角色、标志、音乐或音效。 **故事与设定** 游戏设定在一个原创的太空歌剧背景中：一名被 Threshold Order 驱逐的导航员追踪信号进入 Náris Belt，那里有一支未命名的军事力量守护着回家的通道。启动时，玩家可以在 Arthur Comet 和 Gael Ray 两艘飞船之间做出选择。一次侦察飞行随后升级为与战斗机中队的战斗，并最终面对大型主力舰 Obelisk。 **控制与战斗** 飞行由鼠标引导，鼠标距离屏幕中心的距离控制转向强度；将鼠标移回中心则直线飞行，且不使用指针锁定。键盘绑定包括：巡航速度 (W/S)、翻滚 (A/D)、平移 (Q/E)、双激光脉冲 (鼠标左键)、解锁后的等离子炮 (鼠标右键)、解锁后的能量破裂 (R)、带冷却的加速 (Left Shift)、具有短暂无敌状态且冷却时间为三秒的闪避 (Space)、目标选择与切换 (F, Tab)、暂停 (Esc)、静音 (M) 以及诊断开关 (F3)。等离子炮造成范围伤害，能量破裂是冷却时间为八秒的快速鱼雷。当窗口失去焦点时，任务会自动暂停。 **任务结构** 六个阶段由浅入深：从侦察和拦截侦察机开始，经过规模更大的巡逻队和突击战斗机，解锁等离子炮，面对精英战斗机并解锁能量破裂，削减增援力量，最后通过逐个摧毁 Obelisk 的子系统（防御炮塔、护盾生成器、离子发动机和反应堆）引发连锁反应，完成任务。 **规则与反馈** 护盾在受到伤害五秒后自动再生，而船体完整度则不会再生。摧毁一架战斗机可恢复 7 点护盾。小行星和主力舰会造成碰撞伤害，但不会导致瞬间死亡。“测试飞行”选项可将任务时间加速 4 倍，同时保持移动、武器、伤害和冷却时间不变。 **界面与本地化** 游戏默认语言为英语，并在菜单和暂停界面提供 EN / PT-BR 选择器，选择结果将保存在浏览器中。设定中的专有名词保持不翻译。 **运行与构建** 本地开发需要 Node.js 22.12+ 或 Node.js 24；文档流程为执行 `npm install` 然后 `npm run dev`，服务运行在 `http://127.0.0.1:5173`。在 URL 后添加 `?renderer=webgl&debug` 可强制使用 WebGL2 并启用诊断。生产构建可通过 `npm run build` 和 `npm run preview` 实现。`.github/workflows/deploy.yml` 中的 GitHub Actions 工作流在 `main` 分支推送时构建并将 `dist/` 发布到 GitHub Pages，README 指出该工作流仅请求 GitHub Pages 所需的读取、Pages 写入和部署身份权限。 **架构** 代码组织为多个模块，包括核心（引擎、循环、输入、资源）、玩家（飞行与生命值）、敌人（AI 与编队）、武器（池化投射物与碰撞）、世界（太空环境）、特效、音频、进度、Boss 和 UI。游戏常量位于 `src/config.ts`；战斗和进度测试位于 `tests/`，浏览器冒烟测试位于 `scripts/`。`AssetManager.ship()` 创建临时原语模型，`AssetManager.loadModel(url, parent)` 加载 glTF/GLB 以便未来进行视觉替换。模型面向本地 +Z 轴，且无需外部模型即可运行。系统优先尝试 WebGPU，并自动回退至 WebGL2。 **验证** 文档记录的检查项为 `npm test`、`npm run build`、`npm run dev` 和 `node scripts/browser-smoke.mjs`。冒烟测试需要本地服务器和 Chrome 浏览器，涵盖启动、加速、冲刺、边飞行边射击、实际击杀、暂停、恢复、重启和浏览器错误，并将截图写入临时路径。README 指出六项逻辑测试已通过，且 Chrome/WebGL2 验证确认了射击、边飞行边射击、获得分数的三次击杀、暂停、恢复、重启且无运行时错误，生产构建通过；同时指出在该环境下未验证 WebGPU 以及主力舰战斗的完整浏览器通关流程。 **状态与限制** 该原型包含一个完整的任务，具有胜利、失败和重启状态。飞船和音频被描述为功能性的程序化占位符。艺术纹理、LOD、触摸控制和手柄控制尚未实现。主包大小约为 6.3 MB（gzip 后 1.38 MB），加载优化尚在进行中。目标是在合理的桌面端达到 60 FPS，以 WebGL2 作为参考诊断路径，并为 Google Fonts 提供本地回退。诊断信息可显示 FPS、位置、速度、活跃敌人、投射物、活跃网格和任务时间。 **贡献** 接受通过对 `jeffotoni/deathstar` 进行 fork-and-pull-request 的贡献。README 要求贡献者不要将功能分支推送到官方仓库，使用 Conventional Commits，在 PR 中排除无关的重构，并针对视觉或游戏玩法变更提供面向玩家的结果说明、验证命令以及截图或录像。此外，建议保护 `main` 分支，默认保持 Actions 权限为只读，避免在不可信的 fork 代码中使用密钥，不要提交凭据或生成的构建输出，并根据 `SECURITY.md` 私下报告漏洞。