从零到一：用 CodeArts 构建愤怒的小鸟 HTML5 游戏的实战笔记

本文记录了使用华为云 CodeArts 智能体从零构建一个完整的愤怒的小鸟 HTML5 物理弹射游戏的全过程，涵盖技术选型、架构设计、实战踩坑和优化思考。

一、技术路线

1.1 整体思路

本项目的目标是构建一个零依赖、开箱即用的 HTML5 游戏。技术路线如下：

需求分析 → 架构设计 → CodeArts 代码生成 → 本地部署预览 → GitCode 仓库管理 → 作品展览馆发布

1.2 技术选型

1.3 开发工具链

• CodeArts 智能体：通过 ACP 协议连接 CodeArts 沙箱，发送自然语言描述生成代码
• GitCode：代码托管和版本管理
• DevBridge 隧道：将本地服务暴露给外部访问，用于截图和作品展示
• Gallery 发布流程：8 步标准化发布管线（STS 凭证 → 隧道 → Git 信息 → 封面 → 简介 → 详情 → 训练营 → 发布）

二、架构设计

2.1 游戏核心循环

游戏采用经典的 requestAnimationFrame 主循环：

输入处理 → 物理更新（6步子步积分）→ 碰撞检测 → 状态更新 → 渲染

2.2 物理引擎设计

自研物理引擎是本项目最核心的部分：

• 重力系统：850 px/s² 的向下加速度
• 子步积分：每帧分 6 步更新位置，防止高速物体穿透薄结构
• 三种碰撞模型：
  • 圆-圆（小鸟 vs 猪）
  • 圆-矩形（小鸟 vs 木箱）
  • 矩形-矩形（结构块之间）
• 连锁反应：静态块在撞击力 > 15 时被唤醒，模拟真实物理倒塌

2.3 小鸟能力系统

三种小鸟各有特色能力，通过飞行中触发实现：

• 红鸟：标准弹射，无特殊能力
• 蓝鸟：分裂为 3 只，角度偏移 ±15°，覆盖更大范围
• 黄鸟：冲刺加速 2.5 倍，穿透力更强

三、实战经验

3.1 CodeArts 沙箱目录的坑

问题：首次使用 CodeArts 生成代码时，write 工具报告"写入成功"，但宿主机上看不到文件。

根因：CodeArts 运行在 bwrap 沙箱中，/workspace 是一个 overlay 挂载点，与宿主机路径并非简单的 bind 关系。ACP 的 write 工具写入的路径在沙箱内可见，但宿主机需要通过特定方式访问。

解决方案：改用 bash 工具 + cat heredoc 方式创建文件，明确指定 /workspace/angry-birds/ 路径。同时注意 CodeArts 的 --cwd 只是会话标签，实际文件写入位置由沙箱配置决定。

教训：使用沙箱环境时，务必理解文件系统的映射关系，不能假设路径直接对应。

3.2 物理引擎的子步积分

问题：初版物理引擎每帧只更新一次位置，高速飞行的小鸟会穿透薄结构。

解决方案：引入子步积分——每帧将时间步长分为 6 个子步，每个子步独立检测碰撞。这显著提高了碰撞精度，代价是 6 倍的物理计算量，但对于少量实体（< 20 个）的游戏场景完全可以接受。

心得：游戏物理引擎中，碰撞检测精度比计算效率更重要。穿透问题会严重破坏游戏体验，而现代浏览器的 JS 性能足以支撑适量的子步计算。

3.3 DevBridge 隧道配置

问题：Gallery 发布流程需要 envUrl（外部可访问的 URL）来验证作品可达性，但本地 http://127.0.0.1:8080 无法被外部访问。

解决方案：通过 DevBridge REST API（端口 13000）创建隧道：

1. POST /api/tunnels 创建隧道
2. POST /api/tunnels/:id/ports 配置端口 8080
3. POST /api/host 启动托管
4. 从 GET /api/processes 获取隧道 URL

心得：DevBridge 的 WebUI REST API 比 CLI 更适合自动化场景，返回结构化 JSON 便于程序处理。

3.4 GitCode Token 认证

发现：GitCode API v5 的 token 认证有多种方式：

• Authorization: token <token> → 部分接口 401
• PRIVATE-TOKEN: <token> → ✅ 可靠
• Authorization: Bearer <token> → ✅ 可靠
• ?access_token=<token> → ✅ 可靠

建议：优先使用 PRIVATE-TOKEN header，兼容性最好。

3.5 Gallery 发布的 8 步流程

Gallery 发布流程是一个精心设计的 8 步管线，关键经验：

1. Step 1 STS 凭证：自动创建 IAM 自委托，无需暴露永久 AK/SK
2. Step 3 Git 信息：必须确保 workDir 是 git 仓库根目录，否则会读到父仓库的 remote
3. Step 4 封面：preflight 门禁在 Linux 上可能需要下载 Chromium 和 CJK 字体，首次约 5-10 分钟
4. Step 5 简介：中文字符数严格限制 15-50，需要用 count-cjk.mjs 验证
5. Step 8 发布：幂等键设计防止重复提交，409 冲突时需改名重发

四、存在问题与优化空间

4.1 当前存在的问题

1. 物理引擎精度有限：矩形-矩形碰撞使用 AABB（轴对齐包围盒），不支持旋转体。实际游戏中结构块倒塌时会旋转，但当前引擎忽略了旋转，视觉上不够真实。

2. 音效系统简陋：WebAudio 合成的音效比较粗糙，缺乏层次感。碰撞音效没有根据撞击力度调整音量和音调。

3. 关卡数据硬编码：关卡布局直接写在 game.js 中，无法动态加载或用户自定义。缺少关卡编辑器。

4. 移动端性能未优化：在高 DPI 移动设备上，Canvas 绘制可能掉帧。未实现设备像素比适配和帧率限制。

5. 无离线支持：虽然代码是纯前端，但未配置 Service Worker 和 PWA，无法完全离线运行。

4.2 优化方向

1. 引入旋转物理：升级碰撞检测为 SAT（Separating Axis Theorem），支持旋转矩形碰撞，使结构倒塌更真实。

2. 动态音效：根据撞击力度、材质类型调整音效参数（频率、衰减、音量），提升沉浸感。

3. 关卡系统重构：

   • 关卡数据抽离为 JSON 文件
   • 实现关卡编辑器（拖拽放置结构/猪/鸟）
   • 支持社区关卡分享

4. 性能优化：

   • 实现脏区域渲染（只重绘变化区域）
   • 离屏 Canvas 缓存静态背景
   • 移动端降帧策略（30fps 模式）

5. PWA 改造：

   • 添加 Service Worker 缓存
   • 配置 manifest.json
   • 支持安装到桌面

6. 多人对战：基于 WebSocket 实现轮流发射模式，增加社交属性。

4.3 CodeArts 使用反思

优势：

• 自然语言描述即可生成完整项目，大幅降低初始开发成本
• 生成的代码结构清晰，可读性好
• 支持 bash 工具执行命令，灵活度高

不足：

• 沙箱文件系统隔离导致文件可见性问题，需要额外调试
• 大文件（如 1000+ 行的 game.js）需要分段生成，整体效率有待提升
• 生成的代码需要人工审查和调整，不能完全信任

改进建议：

• 沙箱应提供更清晰的文件路径映射文档
• 支持文件追加模式，避免大文件分段写入的复杂性
• 增加代码自检环节，自动验证语法和逻辑

五、总结

本项目展示了从需求到发布的完整开发链路：

1. CodeArts 生成代码：自然语言 → 完整 HTML5 游戏
2. GitCode 管理代码：创建仓库 → 推送代码 → 版本管理
3. DevBridge 隧道：本地服务 → 公网可访问
4. Gallery 发布：8 步标准化流程 → 作品展览馆

整个过程中，华为云的工具链覆盖了开发、部署、发布的全生命周期。虽然每个环节都有可以改进的空间，但整体体验已经相当流畅。对于快速原型开发和作品展示场景，这套工具链是一个值得推荐的选择。

本文为原创技术博客，转载请注明出处：https://gitcode.com/Eddygit/angry-birds-game