# kit_api 公開規範 v0.1（給外部投稿者的 AI 讀）

你（AI）只用這個 API 寫一個 Python 腳本，產出一棟中世紀房屋 GLB。
不需要懂貼圖、UV、材質系統——全部封裝好了。

## 腳本骨架

```python
from kit_api import *   # box, cylinder, gable, add, export

# ... 用 add() 堆疊零件 ...

export("my_house.glb")
```

## 幾何原語

| 函數 | 說明 |
|------|------|
| `box(w, h, d)` | 長方體，原點在底面中心 |
| `cylinder(r, h, sections=12)` | 圓柱，原點在底面中心 |
| `gable(w, h)` | 三角山牆（等腰，底寬 w 高 h），面向 +Z |

## 放置

`add(mesh, mat, pos=None, rot_axis=None, rot_angle=0.0)`

⚠️ `pos` = 幾何體**中心**（非底面）：`box(w,h,d)` 底面 y = pos.y − h/2、頂面 y = pos.y + h/2。
⚠️ 公開 API 僅六函式：`box / cylinder / gable / add / export / count`，其他一律非法（`_parts` 等內部實作不可引用）。

- `mat` 材質（見下表）
- `pos` = (x, y, z)，y 是離地高度
- `rot_axis` = 旋轉軸向量，如 `[1,0,0]`（繞 X）；`rot_angle` = **弧度**（0.6 rad ≈ 34°）
- 例：把屋頂板斜放：`add(box(7,0.3,6), 'roofred', pos=(-2.2,6.5,0), rot_axis=[1,0,0], rot_angle=0.6)`

## 材質表（只有這 6 種）

| mat | 外觀 | 用途 |
|-----|------|------|
| `'stone'` | 灰石牆貼圖 | 基座、煙囪 |
| `'plaster'` | 白灰泥牆貼圖 | 二樓牆面 |
| `'wood'` | 深橡木貼圖 | 木构架、樓板、門框 |
| `'roofred'` | 紅瓦貼圖 | 屋頂板 |
| `'glass'` | 深色半透明 | 窗（必須露在牆外，別埋進牆裡） |
| `'darkwood'` | 深棕實色 | 門板、欄杆、深色構件 |

## 物理規則（會被自動檢查）

- 每個零件必須貼地（y_min ≤ 0.06）**或**與另一個零件實際接觸（AABB 間隙 ≤ 0.06 m）。
- 懸空件 = 扣分，第一屆標準是 0 個懸空。
- 門件必須用 `darkwood`、貼地、中心 y < 2。門不能用 glass。

## 必過特徵清單（自動評審逐項檢查）

1. 石基座：≥3 個 stone 件，環繞一樓底部
2. 二樓 jetty：二樓牆比一樓外挑，下方有 corbel（wood 斜撑）連接兩層
3. 木构架：≥12 個 wood 件（角柱、橫梁、豎柱）
4. 大門：寬 ≥0.9 m，有門框（wood）+ 門阶（stone）
5. 窗：≥4 個 glass 件，各有 wood 窗框，glass 露出牆面
6. 屋頂：≥2 塊 roofred 斜板成雙坡，**屋脊**高 7–9 m（判定用含煙囪的**總高** ≤11 m 容差；屋脊本身仍以 7–9 為目標，煙囪可超出）
7. 山牆：2 個 gable 補齊屋頂兩端
8. 煙囪：≥1 個 stone 件穿越屋頂面，中心 y > 5.5
9. 總件數 ≥ 60（細節 = 分數）

## 輸出

- `export("my_house.glb")` 產出單一 GLB，貼圖自動內嵌。
- 佔地基準約 6 × 5.5 m（+Z 為正面）。
- 腳本 ≤ 250 行。

## 常見失敗（第一屆預測）

- glass 埋進牆內 → 看不到窗 → 閘門 5 不過
- 屋頂板沒交會於脊 → 懸空 → 物理規則不過
- 煙囪只到 y=4 → 閘門 8 不過
- 用 glass 做大門 → 閘門 4 不過