107 lines
7.9 KiB
Markdown
107 lines
7.9 KiB
Markdown
# AGENTS.md — Star Raid 工作区
|
||
|
||
**这个工作区只做一个项目：Star Raid（像素风竖版弹幕射击游戏）。** 无关项目已移至 `~/Desktop/测试1`，不要在这里新建其他项目的文件。
|
||
|
||
## 项目概述
|
||
|
||
- 客户端：纯 HTML5 Canvas + 原生 JavaScript，**无构建、无依赖、无框架**
|
||
- 服务端：**零 npm 依赖** Node 原生（`node:http` + `node:sqlite`，要求 Node≥22.5），SQLite 存储
|
||
- 240×320 像素画布，竖版弹幕射击（主武器/副武器/僚机/Boss 战/Boss Rush 模式）
|
||
- 账号系统：注册/登陆（用户名+邮箱+密码）、大厅排行榜 Top100、图鉴收集点亮同步
|
||
- 游戏本体在 `star-raid/` 子目录，后端在 `star-raid/server/`，部署见 `star-raid/DEPLOY.md`
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
cd star-raid
|
||
|
||
# 语法检查（每次改完 JS 必须跑；server/ 也要查）
|
||
for f in js/*.js server/*.js; do node --check "$f" || echo "FAIL $f"; done
|
||
|
||
# 启动完整版（游戏+后端，Node≥22.5，自动读取 star-raid/.env）
|
||
node server/server.js # 或 npm start；访问 http://localhost:8643
|
||
# 注意：8643 现由 node server 占用；旧 python http.server 试玩方式已废弃
|
||
# 数据库：默认 ~/.starraid/starraid.db（源码树之外，.env 的 DATA_DIR 可改）
|
||
# 警告：WAL 模式，备份/迁移库文件前必须停服或 wal_checkpoint，直接拷主库会丢数据
|
||
|
||
# Git（仓库根 = 工作区根目录，游戏在子目录）
|
||
git add -A && git commit -m "提交信息"
|
||
```
|
||
|
||
## 验证规则（最高优先级，违反会被用户骂）
|
||
|
||
1. **游戏视觉/手感禁止 Agent 验收**——用户亲自验收。但**账号/大厅/排行榜/结算上报等功能流允许 playwright 测试**（用户 2026-08-06 明确授权）：注册/登陆/数据断言可跑，只是不许用截图评判游戏画面效果。
|
||
2. **游戏玩法改动（武装配置/Boss机制/手感/数值等）默认由用户亲自测试**（用户 2026-08-06 补充）：Agent 不主动跑 playwright 验收这类改动，只做语法检查等静态校验，交付时标注“未做功能验证，待用户验收”；用户明确要求时才跑功能流测试。
|
||
3. 交付时必须诚实标注验证状态。
|
||
4. 完成了操作 ≠ 任务完成，未经验证不得说“修复了/完成了”。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
star-raid/
|
||
├── index.html # 入口 + 全部覆盖层 UI 结构
|
||
├── css/style.css # 全部样式（像素风 UI 变量配色）
|
||
├── server/ # 后端（零依赖 node:http+node:sqlite）
|
||
│ ├── server.js # 入口：静态白名单+/api路由+安全头
|
||
│ ├── env.js # .env 加载（启动最先加载，环境变量优先）
|
||
│ ├── db.js # SQLite schema（users/sessions/user_stats/codex_unlocks/runs）
|
||
│ ├── auth.js # scrypt密码哈希+服务端session
|
||
│ ├── api.js # API处理器；CODEX_KEYS 白名单（新增装备必须同步！）
|
||
│ └── util.js # body解析/限流/输入校验
|
||
├── .env # 本机配置（不进 git；模板 .env.example）
|
||
├── js/
|
||
│ ├── config.js # BAL 平衡参数、常量
|
||
│ ├── data.js # WEAPONS/SUBS/DRONES 装备数据表
|
||
│ ├── core.js # 游戏状态 G、发射逻辑、explodeFx 爆炸特效库
|
||
│ ├── combat.js # 子弹运动/碰撞/光束判定/zones 区域效果
|
||
│ ├── enemies.js # ENEMIES 杂兵表、BOSSES 表、bossMain/bossMinor 攻击库
|
||
│ ├── render.js # 世界渲染（battleUI 门控只在战斗界面绘制游戏对象）
|
||
│ ├── boss_art.js # Boss 美术库（drawProgenitor/drawAssault/drawPiano/drawUsurper/drawSaucer）
|
||
│ ├── sprites.js # 像素字符画 bake 系统、SPR 精灵表、BHALO 弹光晕
|
||
│ ├── audio.js # SFX 音效（WebAudio 合成）
|
||
│ ├── net.js # NET：API 客户端（fetch 封装/图鉴同步/submitRun）
|
||
│ ├── auth.js # 认证流程（登陆/注册/登出 + boot 引导）
|
||
│ ├── home.js # 大厅：排行榜 + 图鉴展柜背景（drawHomeShowcase）
|
||
│ └── ui.js # 菜单/图鉴/rush 选择/老虎机/结算（submitRun 上报）
|
||
├── demo/ # 动作设计 demo（不在静态白名单，公网不可见）
|
||
├── DEPLOY.md # 部署指南（公网/HTTPS/安全边界）
|
||
└── 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/`）沉淀重要约定，发现新约定主动更新
|
||
|
||
## 后端约定（2026-08-06 后端化）
|
||
|
||
- 客户端流程：boot → `/api/me` → 未登录 o-auth（登陆/注册）→ 已登录 o-home（大厅：用户面板+排行榜）→ o-title（基地菜单）
|
||
- 结算上报：`submitRun()`（ui.js）在 endRun 与 rush 胜利（enemies.js killBoss）两处调用；`G.submitted` 防重
|
||
- 图鉴：服务端 `codex_unlocks` 为准，登陆时与本地 SAVE.codex 并集合并；未收集=剪影+???不可演示
|
||
- 背景规则：render() 用 battleUI() 门控；**主页/基地背景=实战模拟**（home.js startHomeSim：随机3主Lv3+3副Lv3+2僚Lv2，G.homeSim 标记，复用 demoSim 自动驾驶刷怪，AU.simMute 静音，不伤/不计分/不上报，主循环看门狗自动重建）；其余空闲=星空。离场必须 G=null（b-home/b-quit/buildRush 已处理）
|
||
- 新增装备时必须同步 `server/api.js` 的 CODEX_KEYS 白名单（现 25+17+13+8=63）
|
||
- 星币/机体/选中机体/永久强化/本地纪录已上服务端（POST /api/state → player_state 表，服务端权威整体替换，登出清空；客户端 persist() 钩子防抖600ms上传）
|
||
- **无尽断点续玩（2026-08-06）**：run_saves 表（每账号1栏位，不分难度），GET/POST/DELETE /api/run_save。波次检查点：startWave 开头 maybeSaveRun() 拍快照（仅无尽+登录态）；中途“暂时退出”不结算（星币/分数留快照）；出击页 resume-slot 卡片续玩（resumeSavedRun：该波从头重打，bossN 不偏移）；新开无尽（不分难度）弹 o-unsaved 确认→settleSavedRun 直接结算旧档（星币入账+上报排行榜+删档）；死亡/通关 endRun 删档。NET._rsQ 串行队列防删建竞态。闯关/rush 不产生云档
|
||
- server/api.js SHIP_KEYS 含全部5机体（曾漏 asura 会致修罗云同步被白名单丢弃，2026-08-06 修）
|