# 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-hans/packages/aigd.supercollider

## 安装

使用 gamedev CLI，在项目文件夹中运行：

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

在桌面应用中：打开 Packages 窗口（状态栏中的包图标），选择 **Browse**，搜索 `aigd.supercollider`，然后点击 **Add to Project**。更多：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** 能力（属于工具中聊天的 Audio 组；随 Audio 一起切换）。项目的 Models 界面（“SuperCollider（音乐）”）决定代理是否可以使用它。代理会获得以下工具：

| 工具 | 作用 |
|---|---|
| `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 秒，会裁剪到所请求时长的精确帧数，不做归一化。种子让作品在语言侧的随机性可复现；但不承诺各平台之间的结果逐位一致。该包不做实时合成，也不安装 Quark 或插件。

四个示例乐谱分别展示了旋律合成器音符（`music.scd`）、带回声尾音的音色（`effect.scd`）、立体声采样（`sample.scd`）以及对齐的打击乐分轨（`loop-stem.scd`）。

### 导出位置

| 项目 | 导出 |
|---|---|
| Unity | `Assets/Audio`，保留已有的 `.meta` 文件及其 GUID。 |
| Godot | `res://Audio/`；`AudioSource` 会生成 `.gdignore`，让 Godot 跳过它。 |
| Unreal | 通过已连接的编辑器导入到 `/Game/Audio`；如果编辑器没有确认导入，你会拿到 WAV 路径，可以自行导入。 |
| 没有引擎的项目 | WAV 文件放在 `AudioSource/exports` 中。 |

把 `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 官方 logo；商标归其所有者所有。
````
