# 《星环弹弓》· Gravity Slingshot

> 微信小游戏 · 完整闭环交付：概念 → 设计 → 开发 → 资源 → 测试 → 部署指引
>
> **一句话玩法**：按住屏幕给轨道充能，松手沿切线弹射——靠星球引力链式弹射，飞向更远深空。

---

## 玩法

竖屏单指休闲小游戏。小飞船靠近星球自动入轨，**按住屏幕 = 充电（轨道收缩）**，**松手 = 沿切线弹射**；充能越满弹得越远，但轨道会不断收缩，缩进大气层就会坠毁（有 3 层护盾）。黑洞会吸入飞船，注意绕开。连续入轨积累连弹（Combo）让得分暴涨，收集星星、冲击里程碑、和微信好友比排行榜。

## 快速开始

### 浏览器试玩（30 秒）

```bash
cd star-ring-slingshot
python3 -m http.server 8000
# 浏览器打开 http://localhost:8000/web/
```

或直接双击打开 `web/index.html`（推荐静态服务，避免 file:// 下音频受限）。

### 微信开发者工具（小游戏本体）

1. 下载安装 [微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)（稳定版）。
2. 导入项目：目录选 `game/`，AppID 填 `touristappid`（测试号，免注册即可跑）。
3. 点"预览"扫码真机试玩；点"上传"可提交代码（需先换正式 AppID）。

## 目录结构

```
star-ring-slingshot/
├── docs/
│   ├── 01-concept.md          # 推荐报告：为什么新颖、为什么吸引人、用户/传播/商业化
│   ├── 02-gamedesign.md       # 权威设计文档：机制/数值/美术/音效/UI/路线图
│   └── 03-deploy-qa.md        # 部署上线 + QA 验收清单（照着做即可发布）
├── game/                      # 微信小游戏工程（开发者工具导入此目录）
│   ├── game.js                # 入口
│   ├── game.json              # 竖屏 + 开放数据域配置
│   ├── project.config.json    # 工程配置（touristappid 测试号）
│   ├── src/                   # 全部游戏代码（CommonJS，可单测）
│   │   ├── world.js           #   纯逻辑：引力/轨道/充电/弹射/计分/生成（零渲染依赖）
│   │   ├── render.js          #   Canvas 2D 绘制（世界/背景/HUD）
│   │   ├── ui.js              #   菜单/结算/暂停/帮助 + 按钮 + 教学提示
│   │   ├── main.js            #   主控制器：输入/状态机/事件→特效·音效·震动/排行榜/广告
│   │   ├── fx.js / audio.js / platform.js / math.js
│   ├── open-data/index.js     # 开放数据域：好友排行榜（getFriendRank + 兜底）
│   └── assets/                # 程序化生成：sfx/*.wav、icon.png、share.png
├── web/                       # 浏览器试玩版
│   ├── index.html / adapter.js（wx API 模拟）/ bundle.js（打包产物）/ assets/
└── scripts/                   # 构建与自测
    ├── gen-audio.js           #   生成 9 个音效 WAV
    ├── gen-icons.js           #   生成 icon.png(144) + share.png(500×400)
    ├── build-web.js           #   打包 web 试玩版
    ├── test-logic.js          #   world 纯逻辑单测（15 项）
    └── smoke-test.js          #   mock wx+canvas 完整 20 秒对局冒烟
```

## 构建与自测

```bash
# 在 star-ring-slingshot/ 目录（需 Node.js ≥ 14）
node scripts/gen-audio.js      # 音效
node scripts/gen-icons.js      # 图标/分享图
node scripts/build-web.js      # 重新打包 web 试玩版
node scripts/test-logic.js     # 15 项逻辑单测（全绿退出码 0）
node scripts/smoke-test.js     # 20 秒模拟对局冒烟
```

实测基准（本仓库当前代码）：

```
PASS ×15（入轨/弹射/连弹/完美弹射/过热坠毁/护盾/黑洞/星星/里程碑/生成/确定性/稳定性…）
冒烟：20 秒对局 · 入轨 5 · 弹射 6 · 得分 2344 · 距离 5.7 KM
```

## 一键变商业化（可选）

`game/src/main.js` 顶部 `CFG.AD_UNIT_ID`：留空 = 无广告；填入流量主激励视频广告位 ID 后，结算页自动出现"看广告复活"。

> ⚠️ 合规提醒：正式商业化发布需游戏版号（见 docs/03-deploy-qa.md §5）。测试/试运营阶段用测试号 + 体验版即可。