Chipgen
使用捆绑的 Node 脚本在本地生成确定性的 8-bit 音乐和音效(SFX)。需要 Node.js 16 或更高版本。
脚本位于此技能文件夹的相对路径 scripts/chipgen.js。使用 node 运行,并将标准输出捕获为 JSON。错误信息写入标准错误输出。
新功能开发、生成的清单以及面向用户的摘要,请优先使用英文。在编辑浏览器 UI 时,保留繁体中文作为辅助语言。
工作流程
- 确定输出目录。如果用户未指定,则使用当前项目中的
generated-audio/目录。 - 根据下面的“摘要转参数”规则,从用户请求中选择参数。如果没有提供种子,则选择一个并报告,以便结果可以复现。
- 当你需要获取有效的情绪、调式或音效类别时,运行
node <skill-dir>/scripts/chipgen.js list。 - 生成请求的资源。当用户要求配乐包、场景集或“不同场景但相同风格”时,使用
music-pack命令。 - 从标准输出读取 JSON 清单,并报告生成的文件路径、种子、情绪/类别、BPM,以及任何 MIDI/分轨/tres 输出。
摘要转参数
从自然语言的游戏音频概述中推断参数。除非请求包含不兼容的约束,否则优先进行合理的初步推断,而不是向用户提问。
音乐情绪选择
- 对于世界地图、旅程、开场、探索、英雄、希望、明亮、标题画面、地图、发现、森林、天空、海洋或通用平台游戏 BGM,使用
adventure(冒险)。 - 对于常规战斗、追逐、危险、动作、限时挑战、敌人波次、快速街机强度、紧张的游戏过程(非Boss战),使用
battle(战斗)。 - 对于Boss、最终Boss、宿敌战斗、高潮、压迫、恶魔、高风险、后期游戏、突袭,或要求“比战斗更激烈”的情况,使用
boss(Boss)。 - 对于城镇、村庄、商店、旅馆、基地、安全区、舒适、友好NPC、制作、农场、轻松菜单BGM或日常场景,使用
town(城镇)。 - 对于洞穴、遗迹、神秘、潜行、迷宫、夜晚、下水道、实验室、外星人、鬼屋、水下、雪/冰(当概述为孤独/寒冷/神秘而非悲伤时),使用
dungeon(地下城)。 - 对于失落、游戏结束、回忆、结局、被摧毁的家园、告别、死亡、孤独、忧郁、情感过场,或雪/冰(当概述明确表达悲伤时),使用
sad(悲伤)。
当概述混合了多种情绪时,优先考虑游戏功能,再考虑情感。例如:“悲伤的Boss战”应为 boss;“孤独的雪地关卡,但不要太慢”通常应为 dungeon 并设置较高范围的BPM,而非 sad。
音乐调式、小节与 BPM
- 直接使用明确的调式请求。当未指定确切调式时,将“小调”的概述映射到
A、D或E。将明亮/英雄/舒适的概述映射到C、F或G。当用户想要惊喜或没有任何调性指示时,使用random。 - 对于快速预览、短循环、插曲或大量候选曲目,使用 8 小节。对于普通循环BGM,使用 16 小节。对于较长的环境/背景音乐请求,使用 32 小节。
- 如果未指定 BPM,让生成器在情绪范围内选择。如果用户要求更快/更慢,将 BPM 设置在所选情绪范围的顶部/底部附近。如果用户说“不要太慢”,除非情感需要,否则避免使用
sad,或者将sad的 BPM 设置在 92 附近。 - 对于最终版或生产就绪的 BGM,请包含
--midi --stems参数。对于探索性生成,除非用户要求单一结果,否则包含--variants 5参数。
音乐包选择
当请求要求一个完整的小型配乐、一个场景包、一组提示音,或一个连贯风格的多个游戏场景音乐时,使用 music-pack 命令。
music-pack 从一个种子家族和一个确定的调式生成六个提示音:
- 主题:
adventure,16 小节 - 城镇:
town,16 小节 - 地下城:
dungeon,16 小节 - 战斗:
battle,8 小节 - Boss:
boss,16 小节 - 结局:
sad,8 小节
这与 --variants 不同。变体保持一个场景不变,只改变衍生种子。音乐包改变场景功能,同时保持调性中心和种子家族连贯。
音效类别选择
- 用于拾取、收集、奖励、宝石、获得道具、得分或确认正反馈,使用
coin。 - 用于菜单确定、接受、正面 UI 点击、小成功或对话继续,使用
confirm。 - 用于返回、拒绝、无效、UI 错误、关闭菜单或负面反馈,使用
cancel。 - 用于跳跃、跳、弹跳、弹簧、UI 向上移动或角色上升,使用
jump。 - 用于冲刺、闪避、快速移动、速度爆发或空中踏步,使用
dash。 - 用于着陆、重踏、沉重脚步声、接触地面或轻微身体撞击,使用
land。 - 用于射击、抛射物、电击、射线、施法、爆破或快速魔法攻击,使用
laser。 - 用于剑、刀刃、利爪、挥砍、切割、近战攻击或快速呼啸击中,使用
slash。 - 用于伤害、重拳、冲击、受伤、击中敌人或身体接触,使用
hit。 - 用于盾牌、招架、防御、护甲受击、格挡或金属/石头撞击,使用
block。 - 用于爆炸、破坏、撞击、爆破、毁坏、木桶、炸弹或巨大冲击,使用
explosion。 - 用于升级、升级、解锁、增益、治疗、稀有物品、成功花彩或变身,使用
powerup。 - 用于治疗、恢复、药水、复活、魔法闪光或温和正面效果,使用
heal。 - 用于传送、消失、扭曲、传送门、重生或相位移动,使用
teleport。 - 用于门、开关、拉杆、门、机关、锁或重型 UI 面板,使用
door。 - 用于宝箱、奖励揭示、物品 fanfare、打开战利品或稀有拾取,使用
chest。 - 用于 UI 光标、菜单移动、小选择、打字、通知、低调哔哔声或中性界面反馈,使用
blip。 - 用于警告、警报、侦测、感叹号、低生命值或定时危险,使用
alert。 - 用于掉落、失败、坠落、失去、错误答案、向下过渡或游戏结束提示音,使用
fall。 - 用于死亡、玩家失败、游戏结束、敌人被击败或戏剧性失败,使用
defeat。 - 用于空气运动、挥击准备、过渡、快速经过或抽象运动,使用
whoosh。
对于重复的游戏音效,生成 --variants 5。对于 UI 音效,生成 3-5 个候选,并通过选择 blip、coin 或 hit 而非 random 来保持时长较短。
命令
列出支持的数值:
node <skill-dir>/scripts/chipgen.js list
生成 BGM:
node <skill-dir>/scripts/chipgen.js music \
--mood battle \
--key A \
--bars 16 \
--seed 42 \
--stems \
--midi \
--out generated-audio/bgm
从同一个种子家族生成 BGM 候选:
node <skill-dir>/scripts/chipgen.js music \
--mood boss \
--key A \
--bars 16 \
--seed 42 \
--variants 5 \
--midi \
--out generated-audio/bgm
生成包含六个提示音的音乐包:
node <skill-dir>/scripts/chipgen.js music-pack \
--key C \
--seed 42 \
--stems \
--midi \
--out generated-audio/bgm-pack
生成一个音效:
node <skill-dir>/scripts/chipgen.js sfx \
--cat coin \
--seed 123 \
--out generated-audio/sfx
为 Godot 生成音效变体池:
node <skill-dir>/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 路径:写入一个 GodotAudioStreamRandomizer资源文件。--res-prefix 前缀:在生成的 Godot.tres文件中使用的资源前缀。
默认设置
对于游戏就绪的 BGM,除非用户只想要快速预览,否则优先使用 --stems --midi。
对于音乐探索性生成,从一个基础种子生成 5-10 个候选。在 CLI 输出中,variantIndex: 0 是基础种子,后续项目使用 variantSeed = (baseSeed + 0x9E3779B9 * index) >>> 0,其中索引从 1 开始。保持 mood(情绪)、已解析的 key(调式)、bars(小节)和 bpm(BPM)固定,使候选曲目感觉相关而非随机。
对于紧凑的游戏配乐,优先使用 music-pack --stems --midi。它从一个种子家族生成主题、城镇、地下城、战斗、Boss 和结局提示音。
对于用于游戏中重复播放的音效,优先使用 --variants 5,并保持相同类别,使用不同的种子变体。
对于 Godot 项目,当这些目录存在时,使用 assets/audio/bgm 和 assets/audio/sfx。提醒用户,Godot 的 WAV 导入可能需要为循环 BGM 启用循环模式。