# SuperCollider

> 在電腦上用 SuperCollider 3.14.1 創作、渲染、分析並匯出可攜式遊戲音樂：專案裡的樂譜即程式碼、離線 WAV 渲染、同步分軌與循環樂段、取樣匯入、預覽，以及匯出到 Unity、Godot 或 Unreal。

- ID: `aigd.supercollider`
- 來源: 官方 (第一方 `aigd.*`)
- 分類: 音訊
- 發佈者: AI Game Dev (`aigd`), 已驗證
- 最新版本: 0.1.12 (發佈於 2026-11-22)
- 授權條款: Apache-2.0
- 需要 AI Game Dev 應用程式: `>=0.25.11`
- 原生程式碼: 否
- 評分: 尚無評分
- HTML 頁面: https://ai-game.dev/zh-hant/packages/aigd.supercollider

## 安裝

在專案資料夾中，使用 gamedev CLI：

```bash
gamedev pkg add aigd.supercollider
```

在桌面應用程式中：開啟「套件」視窗（狀態列上的套件圖示），選擇 **瀏覽**，搜尋 `aigd.supercollider`，然後點 **加入專案**。更多資訊：https://ai-game.dev/docs/wiki/app/packages

## 版本

| 版本 | 發佈日期 | 需要應用程式 | 備註 |
|---|---|---|---|
| 0.1.12 | 2026-11-22 | `>=0.25.11` | 最新 |
| 0.1.11 | 2026-11-19 | `>=0.25.11` | - |
| 0.1.10 | 2026-11-13 | `>=0.25.11` | - |
| 0.1.9 | 2026-11-06 | `>=0.25.11` | - |
| 0.1.8 | 2026-11-06 | `>=0.25.11` | - |
| 0.1.7 | 2026-11-01 | `>=0.25.11` | - |
| 0.1.5 | 2026-10-13 | `>=0.20.0` | - |
| 0.1.4 | 2026-10-09 | `>=0.20.0` | - |
| 0.1.2 | 2026-10-05 | `>=0.20.0` | - |
| 0.1.1 | 2026-10-01 | `>=0.20.0` | - |

## 說明

````markdown
# SuperCollider (`aigd.supercollider`)

搭配 AI Game Dev 代理與 [SuperCollider](https://supercollider.github.io) 創作、渲染、分析並匯出可攜式遊戲音樂。代理會在專案中撰寫 SuperCollider 樂譜（`.scd`），在你的電腦上離線渲染成 WAV，讓你預覽結果，並匯出到你的 Unity、Godot 或 Unreal 專案。一切都在本機執行，完全不消耗你的 AI Game Dev 額度。它適合想把音樂、循環樂段、分軌與效果做成可編輯的原始碼、留在版本控制裡，而不只是成品音訊檔的遊戲開發者。

## 你可以做什麼

- 以可讀、可編輯、可重新渲染的 SuperCollider 程式碼創作主題曲、循環樂段與過場短音。
- 渲染長度與設定都相同的同步分軌（例如打擊與旋律），用於分層或適應性音樂。
- 使用自己的取樣：匯入 WAV，並從樂譜中播放。
- 檢查渲染結果：長度、取樣率、聲道數、峰值、RMS 與削波。
- 在應用程式中預覽渲染結果，再把 WAV 匯出到引擎的音訊資料夾。

## 範例請求

- 「創作一段八秒的柔和探索主題，渲染後匯出到遊戲中。」
- 「做一段 2 秒、48 kHz 立體聲的無縫打擊循環，再加上對應的低音分軌。」
- 「把 `Recordings/door.wav` 匯入為取樣，並用它做出短促的迴響開門音效。」
- 「分析上一次的渲染：有地方在削波嗎？」

## 運作方式

此套件會新增 **Music** 能力（屬於 Tools 中對話的 Audio 群組；會隨 Audio 一起開關）。專案的 Models 畫面（「SuperCollider (music)」）決定代理能否使用它。代理會取得以下工具：

| 工具 | 功能說明 |
|---|---|
| `status`, `get_guide` | 執行階段狀態與撰寫指南。 |
| `init_project` | 建立 `AudioSource` 撰寫目錄結構，並複製經過測試的範例樂譜，絕不覆寫你的作品。 |
| `import_sample` | 把專案中的 WAV 複製到取樣中（小端 PCM、單聲道或立體聲、16/24/32 位元、8–192 kHz），並記錄其 SHA-256。 |
| `render`, `get_render_status`, `cancel_render` | 以本對話的工作項目離線渲染樂譜、追蹤進度並予以取消。 |
| `analyze_audio` | WAV 的長度、取樣率、聲道數、位元深度、峰值、RMS 與削波。 |
| `preview` | 一份簡短但完整的預覽複本，會在桌面應用程式中開啟（CLI 會回傳其路徑）。 |
| `export_to_game` | 把完成的渲染結果匯出到遊戲專案。 |

代理會用一般的檔案工具編輯樂譜。每個 `.scd` 樂譜會回傳一個 `Score`；執行器會以全新的 `scsynth` 在非即時模式下渲染。渲染結果為單聲道或立體聲 PCM16 WAV，取樣率 44100、48000 或 96000 Hz，最長 600 秒，會裁切到所要求長度的精確取樣影格數，且不做正規化。種子可讓作曲在語言端的隨機性可重現；但不保證跨平台結果位元完全相同。此套件不進行即時合成，也不會安裝 Quarks 或外掛。

四份範例樂譜分別示範旋律合成器音符（`music.scd`）、帶有迴響尾音的音色（`effect.scd`）、立體聲取樣（`sample.scd`）以及對齊的打擊分軌（`loop-stem.scd`）。

### 匯出位置

| 專案 | 匯出 |
|---|---|
| Unity | `Assets/Audio`，並保留既有的 `.meta` 檔案與其 GUID。 |
| Godot | `res://Audio/`；`AudioSource` 會加上 `.gdignore`，讓 Godot 略過它。 |
| Unreal | 透過已連線的編輯器匯入到 `/Game/Audio`；若編輯器未確認匯入，你會取得 WAV 路徑，可自行匯入。 |
| 沒有引擎的專案 | `AudioSource/exports` 中的 WAV 檔案。 |

把 `AudioSource`（樂譜、樂器、效果、取樣、預設集、`audio-project.json`、`dependencies.lock`）留在版本控制中；渲染結果可隨時丟棄。

在桌面應用程式中，連上 Unity、Godot 或 Unreal 編輯器的閒置對話會出現兩則提示：一則提醒開啟 Music，接著一則提供八秒的範例主題或讓你自行發想。`/supercollider [status|guide]` 會顯示狀態與指南。

## 執行階段與需求

- **SuperCollider 3.14.1**，首次需要時會從官方 GitHub 發行版下載，並比對固定的 SHA-256：Windows x64 使用 ZIP，macOS 使用 DMG。啟用套件時不會下載任何東西。
- **Linux：**SuperCollider 並未發佈可攜式的 Linux 版本。請把 `runtimePath` 設為相容的 SuperCollider 3.14.1 安裝，或把 `stagedArtifact` 設為經過審查的構件描述檔（版本、平台、URL、SHA-256、格式 `tar`）。
- 每個工作只會使用標準類別庫與外掛執行；你的 SuperCollider 啟動檔與家目錄設定不會被載入或變更。樂譜程式碼是受信任的程式碼，並非安全沙箱。
- AI Game Dev 0.25.11 或更新版本。

## 授權條款

此套件：Apache-2.0。SuperCollider 是其專案以 GNU GPL 釋出的自由軟體。套件頭像是官方 SuperCollider 標誌；商標屬於其擁有者。
````
