# MzTranslator 架構設計

## 概述
使用 Maya Python API 建立一個 `.mz` 檔案格式的 Maya Translator 插件。

## .mz 檔案格式
- 本質是 ZIP 壓縮格式
- 內部包含 `data.ma` 文件（Maya ASCII 格式）

## 系統架構

```mermaid
graph TB
    subgraph Maya
        A[Maya GUI] -->|另存為/開啟| B[mz_translator.py]
    end
    
    subgraph Core
        B --> D[mz_writer]
        B --> E[mz_reader]
    end
    
    subgraph FileSystem
        D --> F[.mz]
        E --> F
    end
```

## 實現步驟

### 1. 文件結構

```
d:/workspace/MzTranslator/
├── mz_translator.py          # 插件入口，包含 MPxFileTranslator 和插件註冊
└── mz_core/
    ├── __init__.py           # 模組初始化
    ├── reader.py             # 讀取模組
    └── writer.py             # 寫入模組
```

### 2. mz_translator.py
- 繼承 `maya.api.MPxFileTranslator`
- 包含 `initializePlugin()` 和 `uninitializePlugin()` 函數
- `writer(fileObject, options)`: 調用 mz_writer
- `reader(fileObject, options)`: 調用 mz_reader
- `haveWriteSupport()` / `haveReadSupport()`: 返回 True
- `fileType()` / `defaultExtension()`: 返回 "mz"
- `optionsScript()`: Export Options UI

### 3. MzTranslator/mz/core/mz_writer.py
- `write_to_mz(filePath, options)`: 將 Maya 場景寫入 .mz
- 內部調用 Maya API 寫入 temp data.ma
- 使用 zipfile 壓縮成 .mz

### 4. MzTranslator/mz/core/mz_reader.py
- `read_from_mz(filePath, buffer)`: 從 .mz 讀取
- 使用 zipfile 解壓縮
- 讀取到內存緩衝區

### 5. Export Options 對話框
- 版本號
- 壓縮等級

## 技術要點

1. **MPxFileTranslator 繼承**: 使用 `maya.app.audio.MPxFileTranslator`

2. **Stream I/O**: reader 使用 buffer/stream 讀取

3. **臨時文件管理**: 使用 `tempfile` 模組

4. **Error Handling**: 處理各種異常情況

## 預期行為

- **保存**: Maya 另存為 → 選擇 .mz → 導出到 temp data.ma → 壓縮成 .mz
- **開啟**: 選擇 .mz 文件 → 解壓讀取 data.ma → 加載到 Maya