# AGENTS.md — Star Raid 工作区

**这个工作区只做一个项目：Star Raid（像素风竖版弹幕射击游戏）。** 无关项目已移至 `~/Desktop/测试1`，不要在这里新建其他项目的文件。

## 项目概述

- 纯 HTML5 Canvas + 原生 JavaScript，**无构建、无依赖、无框架**
- 240×320 像素画布，竖版弹幕射击（主武器/副武器/僚机/Boss 战/Boss Rush 模式）
- 游戏本体在 `star-raid/` 子目录

## 常用命令

```bash
cd star-raid

# 语法检查（每次改完 JS 必须跑）
for f in js/*.js; do node --check "$f" || echo "FAIL $f"; done

# 本地运行（用户试玩用）
python3 -m http.server 8643   # 然后访问 http://localhost:8643
# 注意：8642 端口有浏览器缓存污染，固定用 8643

# Git（仓库根 = 工作区根目录，游戏在子目录）
git add -A && git commit -m "提交信息"
```

## 验证规则（最高优先级，违反会被用户骂）

1. **禁止运行游戏测试视觉效果**——包括 playwright 截图、浏览器数据断言。视觉和手感全部由用户亲自验收。Agent 只做：`node --check` 语法检查 + git 提交。
2. 交付时必须诚实标注验证状态："仅语法检查通过，未运行验证"。
3. 完成了操作 ≠ 任务完成，未经验证不得说"修复了/完成了"。

## 项目结构

```
star-raid/
├── index.html          # 入口 + 全部覆盖层 UI 结构
├── css/style.css       # 全部样式（像素风 UI 变量配色）
├── js/
│   ├── config.js       # BAL 平衡参数、常量
│   ├── data.js         # WEAPONS/SUBS/DRONES 装备数据表
│   ├── core.js         # 游戏状态 G、发射逻辑、explodeFx 爆炸特效库
│   ├── combat.js       # 子弹运动/碰撞/光束判定/zones 区域效果
│   ├── enemies.js      # ENEMIES 杂兵表、BOSSES 表、bossMain/bossMinor 攻击库
│   ├── render.js       # 全部渲染（drawBoss 各 Boss 绘制、zones、子弹）
│   ├── sprites.js      # 像素字符画 bake 系统、SPR 精灵表、BHALO 弹光晕
│   ├── audio.js        # SFX 音效（WebAudio 合成）
│   └── ui.js           # 菜单/图鉴/rush 选择/老虎机/结算
├── demo/               # 动作设计 demo（如 tentacle-sweep.html 触手扫击）
└── research/           # Boss 参考图与调研（不进 git）
```

## 代码规范

- 单文件不超过 500 行；新增大功能先考虑拆模块
- 严格 `"use strict"`；全局函数跨文件直接调用（无模块系统，script 标签顺序加载）
- 编辑技巧：`edit_file` 的 old_string 必须先 grep/sed 读原文确认（含中文注释易有不可见差异）；整批替换任一失败则全部不写入

## 设计禁忌（用户铁律）

1. **AoE 区域效果禁止画圆形区域**——用纯粒子、不规则雾团、电弧（钢琴蓄力圈是唯一批准的例外）
2. **禁止恢复已删除的武器**：弹跳光碟、钻头弹、感应水雷、全息诱饵、圣水领域
3. **武器命中禁止屏幕白闪**（玩家受伤/Boss 死亡的闪光保留）
4. 子弹差异化是最高优先级：颜色/形状/运动/拖尾/命中效果五轴都要拉开
5. Boss 变形=同一几何体连续演化（裂开/展开/伸长/滑开露出），禁止部件凭空出现；俯视图禁止画立体尖塔

## Boss 设计标准

设计或修改任何 Boss 前，必须读取项目记忆 `.astrion/memory/boss_design_standard.md`（视觉公式/攻击节奏/判定同源原则/小兵差异化）。触手扫击类动作设计参考 `star-raid/demo/tentacle-sweep.html` 的"前摇→释放→后摇"三段式。

核心原则一句话：**视觉 = 判定**（碰撞坐标每帧只算一份，渲染与判定同源）。

## 工作流约定

- 大改动先讨论方案再动手；视觉效果由用户验收后再迭代
- 每完成一个逻辑单元立即 git 提交（提交信息写清改了什么+为什么）
- 项目记忆（`.astrion/memory/`）沉淀重要约定，发现新约定主动更新