Communitygithub.com

888wing/8bit-music-generator

一款在地端執行的 Codex 技能,可產生可複現的 8 位元音樂與音效。

8bit-music-generator 是什麼?

這是一款供 AI 代理(如 Codex)使用的技能,能透過本機 Node.js 腳本 `chipgen.js` 產生確定性(具固定隨機種子)的 8 位元音樂與音效。開發者只需以自然語言描述遊戲音訊需求(例如「一場悲傷的魔王戰」),技能便會自動推斷參數——選定情緒、調性、小節數與 BPM——並透過 CLI 指令產生資產。產出包括 WAV、MIDI、分軌音檔,甚至可直接生成 Godot 引擎適用的 `.tres` 資源(含 `AudioStreamRandomizer`),省去手動調整的麻煩。音樂支援六種情緒(adventure、battle、town、dungeon、sad、boss)與完整的配樂包(music-pack)模式;音效則涵蓋 coin、jump、laser、explosion 等 22 種分類。所有結果皆可透過種子碼重現,適合遊戲開發中的快速迭代與版本控制。此技能在 Cursor、Codex 等支援 CLI 的代理平台上均可運作,但需確保環境已安裝 Node.js 16 或更新版本。

相容平台~Claude Code✓Codex CLI✓Cursor
npx skills add 888wing/8bit-music-generator

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Chipgen

使用隨附的 Node 腳本在本機產生確定性(可複現)的 8 位元音樂與音效。需要 Node.js 16 或更新版本。

該腳本位於技能資料夾的 scripts/chipgen.js。以 node 執行,並將標準輸出(stdout)擷取為 JSON。錯誤訊息會寫入標準錯誤(stderr)。

處理新功能、產出清單與使用者面向摘要時,優先使用英文。編輯瀏覽器介面時,則保留繁體中文作為次要語系。

工作流程

  1. 解析輸出目錄。若使用者未指定,則使用目前專案中的 generated-audio/。
  2. 依據下列的簡述轉參數規則,從使用者需求中選擇參數。若未提供種子,則自行選定並回報,以便結果可重現。
  3. 執行 node <技能資料夾>/scripts/chipgen.js list 以查詢有效的情緒、調性或音效分類。
  4. 產生要求的資產。當使用者要求配樂包、場景套件或「不同場景但風格一致」時,使用 music-pack。
  5. 從 stdout 讀取 JSON 清單,並回報產生的檔案路徑、種子、情緒/分類、BPM,以及任何 MIDI/分軌/tres 輸出。

簡述轉參數

從自然語言的遊戲音訊簡述推斷參數。除非請求包含不相容的限制條件,否則優先採用合理的初步推斷,而非反覆提問。

音樂情緒選擇

  • 使用 adventure 用於:地上世界、旅程、開場、探索、英雄、希望、明亮、標題畫面、地圖、發現、森林、天空、海洋、或一般平台遊戲背景音樂。
  • 使用 battle 用於:一般戰鬥、追逐、危險、動作、限時挑戰、敵人群、快速街機強度、或非魔王戰的緊張遊戲體驗。
  • 使用 boss 用於:魔王、最終魔王、勁敵戰、高潮、壓迫感、惡魔、高風險、後期遊戲、突襲、或「比戰鬥更激烈」的場面。
  • 使用 town 用於:城鎮、村莊、商店、旅館、基地、安全區、舒適、友善 NPC、製作、農場、輕量選單背景音樂、或日常場景。
  • 使用 dungeon 用於:洞穴、廢墟、謎題、潛行、迷宮、夜晚、下水道、實驗室、外星、鬼屋、水下、雪地/冰原(當描述強調孤獨、寒冷、神祕而非悲傷時)。
  • 使用 sad 用於:失落、遊戲結束、回憶、結局、毀滅的家園、告別、死亡、孤獨、憂鬱、情感過場動畫、或雪地/冰原(當描述明確帶有哀傷情緒時)。

當簡述混合多種情緒時,先以遊戲功能為優先,其次考慮情感。例如:「悲傷魔王戰」應使用 boss;「孤獨的雪地關卡但不要太慢」通常應使用 dungeon 並搭配較高範圍的 BPM,而非 sad。

音樂調性、小節數與 BPM

  • 直接使用明確的調性要求。將「小調」簡述對應至 A、D 或 E(當未指定確切調性時)。將明亮、英雄、舒適的簡述對應至 C、F 或 G。當使用者想要驚喜或完全沒有調性方向時,使用 random。
  • 快速預覽、短循環、提示音或大量候選時,使用 8 小節。一般循環背景音樂使用 16 小節。較長的環境音/背景需求使用 32 小節。
  • 若未指定 BPM,讓產生器在情緒範圍內自行選擇。如果使用者要求更快/更慢,則將 BPM 設為所選情緒範圍的上限或下限附近。如果使用者說「不要太慢」,則避免使用 sad(除非情緒要求),或將 sad 設定在 92 BPM 附近。
  • 對於最終或正式版的背景音樂,請包含 --midi --stems。對於探索用途,請包含 --variants 5(除非使用者要求單一結果)。

配樂包選擇

當使用者要求完整的迷你配樂、場景套件、一組提示音、或遊戲多場景的統一風格音樂時,使用 music-pack。

music-pack 會從同一個種子家族與一個已解析的調性中產生六個提示音:

  • 主題:adventure,16 小節
  • 城鎮:town,16 小節
  • 地城:dungeon,16 小節
  • 戰鬥:battle,8 小節
  • 魔王:boss,16 小節
  • 結局:sad,8 小節

這與 --variants 不同。變體(variants)會固定一個場景,只改變衍生種子。配樂包則會改變場景功能,同時保持調性中心與種子家族一致。

音效分類選擇

  • coin 用於:拾取、收集、獎勵、寶石、獲得物品、得分、或正面確認。
  • confirm 用於:選單確定、接受、正面 UI 點擊、小成功、或對話繼續。
  • cancel 用於:返回、拒絕、無效、UI 錯誤、關閉選單、或負面回饋。
  • jump 用於:跳躍、彈跳、彈簧、UI 向上動作、或角色抬升。
  • dash 用於:衝刺、閃避、快速移動、加速、或空中踏步。
  • land 用於:著陸、踩踏、沉重腳步、接觸地面、或小型身體撞擊。
  • laser 用於:射擊、投射物、電擊、射線、法術施放、雷射槍、或快速魔法攻擊。
  • slash 用於:劍、刀刃、利爪、揮擊、切割、近戰攻擊、或快速嗖聲擊中。
  • hit 用於:傷害、拳擊、撞擊、受傷、擊中敵人、或身體接觸。
  • block 用於:盾牌、格擋、防守、裝甲擊中、彈開、或金屬/石頭撞擊。
  • explosion 用於:爆炸、破壞、撞毀、爆裂、毀滅、桶子、炸彈、或大型撞擊。
  • powerup 用於:升級、等級提升、解鎖、增益、治療、稀有物品、成功華麗效果、或變身。
  • heal 用於:治療、恢復、藥水、復活、魔法閃爍、或溫和的正面效果。
  • teleport 用於:傳送、消失、扭曲、傳送門、重生、或相位轉移。
  • door 用於:門、開關、拉桿、閘門、機關、鎖、或重型 UI 面板。
  • chest 用於:寶箱、獎勵揭示、物品慶祝音、開啟戰利品、或稀有拾取物。
  • blip 用於:UI 游標、選單移動、小型選擇、打字聲、通知、低調嗶聲、或中性介面回饋。
  • alert 用於:警告、警報、偵測、驚嘆號、低生命值、或限時危險。
  • fall 用於:墜落、失敗、掉落、輸掉、錯誤答案、向下過渡、或遊戲結束提示音。
  • defeat 用於:死亡、玩家失敗、遊戲結束、擊敗敵人、或戲劇性失敗。
  • whoosh 用於:空氣移動、揮擊準備、過渡、快速掠過、或抽象移動。

對於重複使用的遊戲音效,請產生 --variants 5。對於 UI 音效,產生 3-5 個候選並保持時長短促,選擇 blip、coin 或 hit 而非 random。

指令

列出支援的值:

node <技能資料夾>/scripts/chipgen.js list

產生背景音樂:

node <技能資料夾>/scripts/chipgen.js music \
  --mood battle \
  --key A \
  --bars 16 \
  --seed 42 \
  --stems \
  --midi \
  --out generated-audio/bgm

從同一個種子家族產生多個背景音樂候選:

node <技能資料夾>/scripts/chipgen.js music \
  --mood boss \
  --key A \
  --bars 16 \
  --seed 42 \
  --variants 5 \
  --midi \
  --out generated-audio/bgm

產生包含六個提示音的配樂包:

node <技能資料夾>/scripts/chipgen.js music-pack \
  --key C \
  --seed 42 \
  --stems \
  --midi \
  --out generated-audio/bgm-pack

產生單一音效:

node <技能資料夾>/scripts/chipgen.js sfx \
  --cat coin \
  --seed 123 \
  --out generated-audio/sfx

為 Godot 產生音效變體池:

node <技能資料夾>/scripts/chipgen.js sfx \
  --cat hit \
  --seed 88 \
  --variants 5 \
  --tres generated-audio/sfx/hit_pool.tres \
  --res-prefix res://assets/audio/sfx/ \
  --out generated-audio/sfx

參數

支援的情緒有 adventure、battle、town、dungeon、sad 與 boss。

支援的音效分類有 coin、confirm、cancel、jump、dash、land、laser、slash、hit、block、explosion、powerup、heal、teleport、door、chest、blip、alert、fall、defeat、whoosh 與 random。

實用的選項:

  • --bpm N:覆寫產生的 BPM。
  • --bars N:音樂長度。除非使用者另有要求,否則使用 8、16 或 32。
  • --sr N:取樣率。預設為 44100。
  • --midi:匯出音樂的 MIDI 檔案。
  • --stems:匯出音樂的獨立分軌。
  • --variants N:產生種子家族。對音樂而言,固定情緒、已解析調性、小節數與 BPM,並衍生新的種子。對音效而言,固定分類。
  • --no-mix:跳過混合 WAV。
  • --no-normalize:停用音效正規化。
  • --tres 路徑:寫入 Godot AudioStreamRandomizer 資源。
  • --res-prefix 前綴:用於產生的 Godot .tres 檔案內部的資源前綴。

預設值

對於遊戲用背景音樂,優先使用 --stems --midi,除非使用者僅需要快速預覽。

對於音樂探索,從一個基礎種子產生 5-10 個候選。在 CLI 輸出中,variantIndex: 0 為基礎種子,後續項目使用 variantSeed = (baseSeed + 0x9E3779B9 * index) >>> 0,其中 index 從 1 開始。固定 mood、解析後的 key、bars 與 bpm,使候選感覺相關而非隨機。

對於精簡的遊戲配樂,優先使用 music-pack --stems --midi。它會從同一個種子家族產生主題、城鎮、地城、戰鬥、魔王與結局六個提示音。

對於需要在遊戲中重複播放的音效,優先使用 --variants 5,並保持相同分類但使用不同的種子變體。

對於 Godot 專案,當目錄存在時,使用 assets/audio/bgm 與 assets/audio/sfx。提醒使用者 Godot 的 WAV 匯入可能需要啟用循環模式才能讓背景音樂循環播放。

相關技能