JOJO
9edc366cf9
①图鉴隐藏测试模式：连点标题'军'字10次开关，纯内存标志位全部军械可见可演示，不动SAVE.codex（persist/submitRun读它，动了会污染后端），刷新失效 ②24件主武器说明文案全部替换（用户提供梗文案）；演示页介绍单行显示、去掉类别前缀、删'实战模拟·自动驾驶'提示行 ③新主武器'巡飞弹'(loiter)：慢攻速追踪导弹（制导引擎新增maxSpd上限5保持中速），命中留火场（zones新kind:fire纯粒子火舌，无圆形区域）+分裂4枚小炸弹快爆；新精灵loms；CODEX_KEYS同步63 ④存档云同步：星币/机体/选中机体/永久强化/本地纪录上服务端（player_state表+POST /api/state+vState白名单清洗）；login/me/register响应带state；客户端persist()钩子防抖600ms自动上传；服务端整体替换本地防串号，登出全清；老账号首登自动上传本地存档迁移 ⑤机体选择/购买从出击准备并入机库强化（buildShips）；出击默认无尽模式 服务端已重启生效；/api/state全链路在独立测试库curl验证通过（合法推送/回读/非法拦截清洗/401）
104 lines
6.8 KiB
Markdown
104 lines
6.8 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. 交付时必须诚实标注验证状态。
|
||
3. 完成了操作 ≠ 任务完成，未经验证不得说“修复了/完成了”。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
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上传）
|