# shipyard — 舰船设计器(结构一 / 主画面)

> 自包含的 feature 模块:**造一艘战舰**的所见即所得设计器。
> 这是游戏「结构一主画面」的原型,以后可独立升级,并最终搬进 Bevy。

装/卸模块 → 船上即时长出/移除炮塔·护盾罩·引擎焰,右侧属性实时重算,带**电力预算约束**。
船体与全部模块都是 **AI(Kunavo / gpt-image-2)生成的真美术**。

```
┌ 顶栏:舰船设计局 ───────────────────────────┐
│ [护卫][巡洋][泰坦]      ╱◣ 真·AI 船体 ◢╲       配置 Loadout │
│ 武器 离子炮…           （挂点上摆真模块）      武器 离子炮  │
│ 引擎 聚变…              ◢██████◣  护盾罩       引擎 曲速核心│
│ 护盾/传感/装甲…           ▼引擎焰              属性条 + 电力 │
└──── 点槽位选中 → 点模块装配 · 再点已装卸下 ──── 下水建造 ──┘
```

## 快速开始

纯前端(Pixi7,无构建)。任选其一跑起来:

```bash
# 在本目录起个静态服务器(推荐,贴图走 http 不被 CORS 拦)
cd shipyard && python3 -m http.server 8137
# 浏览器打开 http://localhost:8137
```

直接双击 `index.html` 多数情况也能看,但部分浏览器对 `file://` 下的贴图有 CORS 限制,建议用上面的服务器。

## 它怎么工作

**架构 = HTML/Pixi UI 外壳 + 一块 canvas 渲染舰船** —— 这正是整个游戏「网页生产蓝图」的 UI 层形态:
四周面板是 HTML/CSS(目录/属性/按钮),中间 `<canvas>` 用 Pixi 合成「船体 + 模块精灵」。
将来生产版里,**这块 canvas 换成 Bevy-WASM**,设计器预览与战斗用同一渲染 → 真正的所见即所得。

数据驱动,改表即改玩法(都在 `index.html` 的 `<script>` 顶部):
- `HULLS` — 3 种船体:基础属性 + **挂点表 `hp`**(每个挂点 `{t:类型, fx,fy:相对船心比例}`)。
- `MODULES` — 14 个模块,5 类(`weapon/engine/shield/sensor/armor`),每个带属性增量 `s{fp,range,speed,shield,hp,power}`。
- `MODSPRITE` — 模块 id → 贴图文件名;`TYPE_ROT/TYPE_SCALE` — 按类型定朝向与大小。
- 合成:船体+模块+发光+护盾都挂在 `shipRoot` 容器里,**每帧整体移到屏幕中心,子件用相对船心坐标**
  (这样 resize / 重载都不会错位 —— 早期版本曾因「一次性用 center() 定位」在重载后把模块钉到左上角)。
- 结算:`compute()` = 船体基础 + 各模块增量;**电力**:Σ模块耗电 vs 船体预算,超了红字告警(可玩的取舍)。

## AI 美术产线(脚本)

两个脚本,出的都是**纯黑底生成 → 四角 flood-fill 抠透明**的精灵(gpt-image-2 不给真透明,故黑底+抠图):

- **`gen_sprite.py`** — 通用出图助手(单张;**出图即自动降采样**,`--max` 默认 512、背景图加 `--max 0`)。
  ```bash
  # 文生图
  python3 gen_sprite.py --prompt "..., top-down, pure black background" --out assets/mod_xxx.png
  # 图生图 i2i:传现有舰船当参考,保持风格统一
  python3 gen_sprite.py --prompt "..." --out assets/mod_xxx.png --ref assets/ship_titan.png
  # 背景图等不要透明
  python3 gen_sprite.py --prompt "..." --out bg.png --no-alpha --size 1536x1024
  ```
- **`gen_modules.py`** — 一键重生成全套模块(本目录的 6 张 `mod_*.png`)。改 `MODULES` 列表即可增删。
  ```bash
  python3 gen_modules.py     # 输出到 ./assets/
  ```

**Kunavo 接口**:`POST https://api.kunavo.com/v1/images/generations`(文生图)/ `/v1/images/edits`(图生图);
`Authorization: Bearer <key>`;model `gpt-image-2`(也有 `nano-banana-pro/2`);返回 `data[0].url`(临时,约 24h)。
**key 放 `/tmp/.kunavo_key`**(重启会清,需重新写入;脚本也认环境变量 `KUNAVO_KEY`)。

## 怎么加一个模块 / 船体

1. **出图**:`python3 gen_sprite.py --prompt "<模块描述>, top-down, pure black background" --out assets/mod_新.png`
   (想和现有风格一致就加 `--ref assets/ship_cruiser.png`)。
2. **登记模块**:在 `index.html` 的 `MODULES` 里加一项(类型 + 属性增量),`MODSPRITE` 里加 `id→'mod_新'`。
3. **加船体**:`HULLS` 里加一项(贴图 + 基础属性 + 挂点表 `hp`),把新 `ship_*.png` 放进 `assets/`。

## 文件清单

```
shipyard/
  README.md          本文档
  index.html         设计器(Pixi7,自包含,引用 ./assets/)
  gen_sprite.py      通用出图+抠透明产线
  gen_modules.py     一键重生成全套模块
  assets/
    ship_{corvette,cruiser,titan}.png   3 船体(真·AI)
    mod_{turret,plasma,missile,engine,sensor,armor}.png  6 模块(真·AI)
    fx_{glow,shield}.png  引擎尾焰光晕 / 护盾罩
    nebula.png            背景星云
    fonts/sci.ttf         Rajdhani(科幻 HUD 字体)
```

## 升级方向(以后做)

- **挂点精对齐**:目前挂点坐标是估的,逐船把武器/引擎位对到船体真实硬点。
- **目录真图标**:左侧模块目前是色块,可批量出小图标。
- **更多内容**:更多舰种/武器/防御;模块分 tier;拖拽装配;模块互斥/前置。
- **存档**:`ShipDesign{hull, slots:[moduleId]}` 序列化(对应 Bevy 端 serde+ron),设计可保存/分享。
- **★ 搬进 Bevy(生产路径)**:把这块预览换成 Bevy canvas —— 船体 + 子精灵模块(挂点=父子 Transform),
  复用 Bevy 的 HDR+Bloom 自发光;**设计出的船 = 战斗里开出去的船**(同一渲染 + 同一 `ShipDesign` 数据,
  喂给 `tactical.rs`,顺手补「战斗接真实舰队数据」那个待办)。四周 UI 仍用这套 HTML/Pixi。