# 魔芋の松果

> Pinecone —— 一个纯静态、零构建、离线可用的小游戏合集。

一堆小游戏，收在一颗松果里。捡一颗，玩一局。

![导航页](docs/nav.png)

## 它解决什么

| 问题 | 这个框架的做法 |
|---|---|
| 加游戏要改导航页 | 导航页只读 `games.js`，由扫描器从每个游戏的 `game.json` 生成 |
| 元数据写错没人发现 | `scan-games.mjs` 校验字段、路径、体积、命名，写错直接报错 |
| 打开要起服务器 | 纯静态 + 经典 `<script>`，双击 `index.html` 就能用（`file://` 可用） |
| 每个游戏风格各异 | `_template/` 提供统一骨架，`AGENTS.md` 规定技术规范与验收清单 |

## 快速开始

```bash
# 本地预览（每次请求 games.js 都会自动重扫，改完刷新即可）
node tools/serve.mjs
# → http://127.0.0.1:5173

# 或者直接双击 index.html
```

## 加一个游戏（三步）

```bash
# 1) 脚手架：生成 <slug>/game.json + index.html + README.md
node tools/new-game.mjs snake --title "贪吃蛇" --tags "街机,休闲" --emoji "🐍"

# 2) 写游戏逻辑（只动 snake/ 里的文件）

# 3) 重新生成清单 + 自检
node tools/scan-games.mjs
node tools/scan-games.mjs --check
```

也可以完全手动：建目录 → 写 `game.json` → 写 `index.html` → 跑 `node tools/scan-games.mjs`。

- **完整步骤**（模板骨架、设计要点、自检清单）→ [docs/new-game-guide.md](./docs/new-game-guide.md)
- **怎么计分**（0–1 的 rating 怎么算、怎么防改分）→ [docs/rating-guide.md](./docs/rating-guide.md)

## 目录

```
index.html      导航页（唯一允许出现在根目录的 HTML）
AGENTS.md       规则入口：定位 + 铁律 + 任务索引
games.js        自动生成的游戏清单，勿手改
DESIGN.md       设计规范（配色 / 字体 / 组件 / 统一机制）
design/         设计系统：tokens.css · components.css · pixel-icons.js · logo · styleguide.html
assets/         导航页布局与逻辑
sdk/            共享运行时：konjac-rating.js（计分）
server/         可选后端：自托管 Node（零依赖，数据存 SQLite）
tools/          扫描 / 脚手架 / 评分预览 / 生成 logo / 本地服务器（Node，零依赖）
_template/      新游戏模板
docs/           文档：新建游戏 · 计分 · rules/（拆分后的规则）
<game>/         每个小游戏：game.json + index.html + README.md
```

## 计分

游戏要记分，引一行脚本就行，**不需要登录**：

```html
<script src="../sdk/konjac-rating.js"></script>
<script>
  KonjacRating.submit({ seed, inputs, logicVersion });   // 交一局
  KonjacRating.subRating();                              // 这个游戏的 rating（0–1）
</script>
```

身份是一个随机设备 ID（存在 localStorage）+ 可选昵称，没有注册和密码。
成绩存在服务器上，换设备用 ID 登录就能看到；导航页的卡片上会显示你的 rating 和评分。

**想跨设备看榜单**：起一个后端，把地址填进 `sdk/config.js`。**不部署也照常玩。**

后端只有一个：[`server/`](./server/README.md)——一个 Node 进程，零依赖，数据存 SQLite。

详见 [docs/rating-guide.md](./docs/rating-guide.md)。

## 设计

风格是 **温馨像素（Cozy Pixel）**：暖土色系 + 直角 + 2px 描边 + 无模糊硬阴影 + 点阵图标。

**导航页和所有游戏共用同一套设计变量**——游戏只要引入 `../design/tokens.css` 和
`../design/components.css`，配色、字号、按钮、卡片就自动和站点一致。

- 规范：[DESIGN.md](./DESIGN.md)
- 可视化参考：[design/styleguide.html](./design/styleguide.html)（`node tools/serve.mjs` 后访问 `/design/styleguide.html`）

## 命令

| 命令 | 作用 |
|---|---|
| `node tools/serve.mjs [port]` | 本地服务器，默认 5173，自动重扫 |
| `node tools/scan-games.mjs` | 扫描并生成 `games.js` |
| `node tools/scan-games.mjs --check` | 校验元数据 + 检查清单是否最新（CI 用） |
| `node tools/new-game.mjs <slug>` | 从模板脚手架新游戏 |
| `node tools/new-game.mjs --help` | 查看脚手架参数 |

> 装了 npm 的话也可以用 `npm run serve` / `npm run scan` / `npm run check`。
>
> ⚠️ 如果 PowerShell 报「禁止运行脚本」（`npm.ps1` 被 ExecutionPolicy 拦截），
> 直接用上面的 `node tools/...` 命令即可，不依赖 npm。

## 规则

**入口是 [AGENTS.md](./AGENTS.md)**（定位 + 七条铁律 + 任务索引），
详细规则按任务拆在 `docs/rules/` 里，用到哪个读哪个。

## 版本管理

Git 已初始化，首个提交是框架骨架。

- 提交前跑 `node tools/scan-games.mjs --check`，确保 `games.js` 与各 `game.json` 同步。
- **`games.js` 需要提交**（`file://` 直接打开时靠它加载清单），不要加进 `.gitignore`。
- 提交信息格式见 [docs/rules/ship.md](./docs/rules/ship.md)。

## 环境

只需要 Node ≥ 18（仅用于工具脚本）。游戏本身不需要任何运行时。