Add prototype gameplay loop with character/battlefield assets and server game APIs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-20 18:50:00 +08:00
parent 79369e4473
commit 6c64210331
833 changed files with 998079 additions and 1042 deletions
@@ -0,0 +1,33 @@
+# 主界面背景音乐：糖果营地
+
+制作日期：2026-10-20。用途：Candy 风格营地主界面，伙伴收集与轻策略游戏的日常停留背景。
+
+风格依据为 `GameDesign.md`、`Doc/Design/UI/UI_Themes.md` 与 `Doc/Design/UI/Home/home_generation.json`：阳光、奶油色小屋、绿色原野、喷泉和可爱动物伙伴。配器目标为柔和马林巴/木琴短旋律、木吉他分解和弦、拨弦、温暖低音、轻木管与少量铃音，情绪欢迎、轻松、有准备出发的探索感。完整英文提示词保存在 `generation.json` 的 `prompt`。
+
+## 成品
+
+| 文件 | 用途与规格 |
+| --- | --- |
+| `AIClient/Assets/Bundles/Sound/BGM/CandyCamp_MainMenu_Loop.ogg` | 主界面循环候选成品，90.9秒、48000 Hz、立体声 Vorbis，1,621,586字节 |
+| `CandyCamp_MainMenu_Source.mp3` | 未修改的DGX原曲，94秒、48000 Hz、立体声、128 kbps，留档及试听 |
+| `server_metadata.json` | 服务返回的原始生成元数据，含实际种子、caption与LM规划 |
+| `generation.json` | 风格提示词、生成参数、循环处理参数、音频验证与SHA-256 |
+| `unity_validation.json` | Pipeline验证后的AudioClip规格、导入设置与资源收集信息 |
+
+## 生成
+
+严格按 `D:/UD/AI/XModel/DGX音乐_AI调用指南.md` 调用局域网DGXA音乐服务。模型 `acestep-v15-xl-sft`，LM `acestep-5Hz-lm-4B`；50步、CFG 7、思考开启、批量1、空歌词、无人声提示词。用户未指定时长与BPM，保持时长 `-1`、BPM `null`，交由LM规划；未更换权重或启动参数。
+
+服务种子为 `1430014797`，LM规划200 BPM、C major、三拍、94秒。BPM及拍号为服务规划值，尚未人工确认实际节拍。服务元数据中的 `instrumental: false` 为其内部默认标记；调用接口按指南不额外添加纯音乐字段，无人声意图通过空歌词与提示词表达，实际人声有无仍以试听为准。
+
+生成入口为 `Tools/generate_main_menu_music.py`，原始请求、队列事件、返回和下载记录保留在 `Tools/output/main_menu_music/`。任务ID `89793b8b202341b0944499ce482d1124`。首次SSE订阅在会话创建前返回session_not_found；脚本恢复到同一session与event_id读取结果，只提交了一次生成请求，没有重复排队。
+
+## 循环处理与验证
+
+`python Tools/prepare_main_menu_music.py` 在Unity外处理原始音频：按LM规划的小节长度裁至92.7秒，去掉尾部明显衰减，首尾以1.8秒（两个规划小节）等功率交叉淡化，并旋转接缝到连续波形处。全局降低约1.34 dB后输出Vorbis质量5，得到90.9秒。OGG容器避免MP3编码填充影响循环长度；并未宣称已通过人工听感的无缝音乐衔接。
+
+完整解码成功，采样有限且无削波；OGG解码峰值约-3.17 dBFS，RMS约-20.90 dBFS；循环边界采样差约0.00797，小于内部相邻采样差的99百分位0.05113。上述为技术检查，不能替代旋律、节奏及有无人声的人工试听。
+
+Unity导入与验证使用项目的 `unity-pipeline` 技能：`import_asset` 导入，然后执行 `AIClient/AgentScripts/ImportMainMenuMusic.cs` 的 `ConfigureAndVerify`。AudioClip实际为4,363,200采样帧、90.9秒、双声道、48000 Hz。导入设置为Vorbis质量0.7、CompressedInMemory、保留采样率、后台加载、不预加载，避免启动即展开整首PCM。Art包新增Sound组，仅收集 `Assets/Bundles/Sound/BGM`，按文件名寻址、单独打包；原有收集项保留。本轮Console游标558之后无新增错误。
+
+本次完成生成、循环处理、Unity入库、收集配置与资源登记；未添加AudioSource或运行时播放代码，未接入设置页音乐开关，未构建Bundle、发布CDN或进行微信真机验证。音乐听感和最终循环衔接待试听确认。
@@ -0,0 +1,44 @@
+{
+  "date": "2026-10-20",
+  "model": "acestep-v15-xl-sft",
+  "lm_model": "acestep-5Hz-lm-4B",
+  "inference_steps": 50,
+  "seed": 1430014797,
+  "planned_bpm": 200,
+  "planned_key": "C major",
+  "planned_meter": "3",
+  "prompt": "Original instrumental background music for a cozy, colorful Candy-style mobile game's main menu: a sunny miniature village camp, cream cottages, green meadows, a little fountain, friendly cute animal companions and a gentle sense of preparing for an adventure. Warm, welcoming, playful and relaxed, cheerful without being hyperactive. A memorable but understated short pentatonic melody on soft marimba and wooden xylophone, answered by a mellow flute or clarinet; light nylon-string acoustic guitar arpeggios, pizzicato strings, rounded upright bass and very delicate shaker and woodblock percussion. A few soft celesta sparkles, warm acoustic chamber arrangement, moderate gently bouncing walking pace, clear major-key harmonies. Instrumental only, no singing, no humming, no choir, no speech. Small recurring A and B phrases with subtle variations, stable gentle dynamics and lots of breathing space for menu interactions. Designed for comfortable repeated listening, a short pickup and a final phrase that naturally returns to the opening harmony, loop-friendly structure, no dramatic buildup, no big finale, no heavy drums, no aggressive brass, no distorted guitars, no EDM drops, no environmental sound effects. Polished clean stereo game soundtrack.",
+  "lyrics": "",
+  "source": {
+    "file": "CandyCamp_MainMenu_Source.mp3",
+    "seconds": 94.0,
+    "sample_rate": 48000,
+    "channels": 2,
+    "bitrate": "128 kbps",
+    "sha256": "65f7c8fe5f799adc1121bed3bf166a43ee2161f1297f6bf33491786bd491ddb8"
+  },
+  "loop": {
+    "asset": "AIClient/Assets/Bundles/Sound/BGM/CandyCamp_MainMenu_Loop.ogg",
+    "seconds": 90.9,
+    "sample_rate": 48000,
+    "channels": 2,
+    "bytes": 1621586,
+    "codec": "Vorbis",
+    "quality": 5,
+    "source_end_seconds": 92.69999999999999,
+    "crossfade_seconds": 1.7999999999999998,
+    "gain_db": -1.3376273615099534,
+    "decoded_peak_dbfs": -3.171337127685547,
+    "decoded_rms_dbfs": -20.89783477783203,
+    "boundary_sample_delta": 0.007966671139001846,
+    "internal_sample_delta_p99": 0.05112835392355919,
+    "sha256": "59fb32c3dc42efd2183fefd8c82a76d5068c270a772fd6bec154684eaebe7294"
+  },
+  "verification": {
+    "decode": "passed",
+    "finite_samples": true,
+    "clipping": false,
+    "musical_seam": "Two planned bars crossfaded; human listening review pending",
+    "runtime_playback": "Not wired; resource generation/import only"
+  }
+}
@@ -0,0 +1,20 @@
+{
+  "asset": "Assets/Bundles/Sound/BGM/CandyCamp_MainMenu_Loop.ogg",
+  "guid": "c2de2ab8cb8c4c340a9ac699a274cc40",
+  "length": 90.9,
+  "samples": 4363200,
+  "channels": 2,
+  "frequency": 48000,
+  "loadType": "CompressedInMemory",
+  "compression": "Vorbis",
+  "quality": 0.7,
+  "loadInBackground": true,
+  "preloadAudioData": false,
+  "package": "Art",
+  "group": "Sound",
+  "address": "CandyCamp_MainMenu_Loop",
+  "packRule": "PackSeparately",
+  "runtimePlaybackWired": false,
+  "bundleBuilt": false,
+  "verifiedUtc": "2026-10-20T09:55:34.2279400Z"
+}
@@ -0,0 +1,41 @@
+# 主界面轻柔配乐：微风小镇
+
+2026-10-20，根据用户“类似宫崎骏电影配乐的风格，更轻柔一些”的反馈生成。用户随后确认“这首音乐可以，就用这首吧”，现正式选作主界面背景音乐；《糖果营地》原版作为历史候选保留。取手绘动画电影里微风、原野、小镇和温暖童话的氛围，以原创旋律创作，不引用已有电影主题。
+
+编曲提示以柔和钢琴为主，木管偶尔呼应、少量持续弦乐和竖琴，旋律舒展、音符稀疏、和声变化缓慢，弱化木琴和拨弦节奏，去掉鼓与明显打击乐。完整提示词见 `prompt.txt` 和 `generation.json`，有无人声及最终听感以人工试听为准。
+
+## 生成与成品
+
+依 `D:/UD/AI/XModel/DGX音乐_AI调用指南.md` 调用DGXA音乐服务：`acestep-v15-xl-sft`、50步、CFG 7、LM思考开启、单首、空歌词，参考音频留空。未指定数字BPM和时长，保持BPM null、时长-1。服务返回种子 `2085836397`，规划120 BPM、E major、4拍、87秒；这些是LM规划值，未进行人工节拍确认。
+
+- 原曲：`MeadowBreeze_MainMenu_Source.mp3`，87秒、48000 Hz、立体声、MP3 128 kbps。
+- 循环候选：`AIClient/Assets/Bundles/Sound/BGM/MeadowBreeze_MainMenu_Loop.ogg`，84秒、48000 Hz、立体声、Vorbis质量5，1,408,223字节。
+- 原始服务回执：`server_metadata.json`；加工与校验：`generation.json`；Unity回执：`unity_validation.json`。
+- 任务ID：`9ae35ea3603e459daf1273c5f04f5fdf`，完整队列记录留在 `Tools/output/main_menu_music_soft/`，仅提交一次生成。
+
+原曲按规划小节裁至86秒，进行2秒（一个规划小节）首尾等功率交叠，旋转到连续波形位置，输出84秒OGG。按RMS目标-24 dBFS降低音量，保留原有动态；成品实测RMS -24.003 dBFS、峰值-9.168 dBFS。前一版OGG的RMS约-20.90 dBFS，便于以较低平均音量作菜单背景。完整解码正常、采样有限、无削波；边界采样差0.002665，低于内部采样差99百分位0.01494。技术检查不等同于音乐衔接的人工试听。
+
+## 复现入口
+
+生成脚本支持独立输出目录与提示词文件；已有任务回执时恢复原任务，不重复提交：
+
+```powershell
+python Tools/generate_main_menu_music.py --output Tools/output/main_menu_music_soft --prompt-file Doc/Design/Sound/MainMenuSoft/prompt.txt
+python Tools/prepare_main_menu_music.py --work Tools/output/main_menu_music_soft --design Doc/Design/Sound/MainMenuSoft --stem MeadowBreeze_MainMenu --title 'Meadow Breeze - Main Menu' --crossfade-bars 1 --target-rms-dbfs -24
+```
+
+上述生成目录已有完成结果，脚本会拒绝再次提交；若要同种子重制，需按指南在新请求中设置随机种子关闭及种子字符串，不覆盖本次记录。
+
+Unity通过Pipeline的 `import_asset` 导入新路径，然后运行 `AgentScripts/ImportMainMenuMusic.cs` 的 `ConfigureSoftAndVerify`；设置CompressedInMemory、Vorbis质量0.7、保留采样率、后台加载、不预加载。复用Art/Sound目录收集、按文件名寻址、PackSeparately。Unity回读4,032,000采样帧、84秒、2声道、48000 Hz，验证通过；Console游标559之后无新增错误。
+
+初次生成时仅完成候选入库；`unity_validation.json`、`generation.json` 保留该阶段原始回执。用户已试听确认选用，当前接入状态以以下说明及 `playback_assets.json`、`playback_validation.json` 为准。
+
+## 正式选用与播放接入
+
+播放器Prefab为 `Assets/Bundles/Sound/Prefab/MainMenuMusic.prefab`，由Pipeline执行 `BuildMainMenuMusic.Build` 制作。AudioSource持久引用本曲，2D、循环、音量1、不自动PlayOnAwake，配合 `MainMenuMusic` 组件播放；音量可在Prefab调节。Prefab收集到Art/Sound，按文件名地址 `MainMenuMusic`、PackSeparately。
+
+`GameplayBootstrap`在HUD绑定后通过现有YooAsset路径异步加载Prefab，每个Bootstrap仅创建一次，持有资源句柄至销毁。浏览主界面、营地、设置等菜单连续播放；进入战斗或弹珠页暂停，回菜单续播。音乐开关独立于音效开关，关闭暂停、开启从原位置续播；切后台暂停，回前台按用户偏好恢复。不修改业务UI骨架。
+
+`VerifyMainMenuMusic.Play` 的Boot实播验证通过：实际选曲、采样前进、3轮设置开关及菜单往返不重启、不叠音，音乐/音效开关组合正确；进入弹珠暂停、切换偏好不误恢复、返回首页续播；玩法门控、应用暂停恢复、84秒曲尾回环通过。战斗使用同一门控，未为验证开启服务端战斗。测试恢复原音乐/音效偏好及监听音量；退出Play后恢复原启动场景选项，三个原角色预览场景及未保存标记保留。编译通过，本轮Console游标561之后无新增错误。
+
+未构建Player或Bundle，未发布CDN。正式版本需包含新增音乐Prefab、配套音频及更新后的热更程序集；微信首次交互与音频解锁需真机验证。
@@ -0,0 +1,46 @@
+{
+  "date": "2026-10-20",
+  "model": "acestep-v15-xl-sft",
+  "lm_model": "acestep-5Hz-lm-4B",
+  "inference_steps": 50,
+  "seed": 2085836397,
+  "planned_bpm": 120,
+  "planned_key": "E major",
+  "planned_meter": "4",
+  "prompt": "Original instrumental main-menu music for a cozy pastoral fantasy game, with the tender, airy storytelling atmosphere of a hand-drawn Japanese animated feature: a quiet green village, small cream cottages, a little fountain, friendly animal companions, sunlight moving through leaves and a gentle breeze before a small adventure. Much softer and calmer than a bouncy casual-game tune. Slow, unhurried adagio feel, delicate and intimate, quietly hopeful with a trace of wistful wonder. Soft felted acoustic piano is the main voice, playing a simple lyrical original melody with long singing phrases, rests and light broken chords. A warm breathy flute or clarinet answers only occasionally; a small string ensemble holds very thin, soft sustained harmonies in the background, with a few quiet harp notes. Warm major-key colors, occasional gentle modal shading and spacious add9 or sixth chords, subtle natural room reverb, tender chamber-orchestra sound. Pianissimo to mezzo-piano throughout, soft rounded attacks, sparse notes, slow harmonic changes, plenty of silence between phrases, low density and no energetic pulse. No drums, no shaker, no woodblock, no busy pizzicato, no prominent marimba or xylophone, no bright music-box ostinato, no heavy bass, no sharp staccato, no heroic brass, no epic crescendo, no dramatic climax, no EDM or synth beat. Entirely instrumental: no singing, no humming, no choir, no spoken words, no environmental sound effects. A small original A-B-A theme with restrained variations, suitable for comfortable repeated listening beneath menu interactions. Keep the opening and final phrases in compatible harmony and texture, a brief gentle entrance, no long silent ending and no grand finale. Clean stereo acoustic film-score production. Compose an original melody, without quoting any existing film theme.",
+  "lyrics": "",
+  "source": {
+    "file": "MeadowBreeze_MainMenu_Source.mp3",
+    "seconds": 87.0,
+    "sample_rate": 48000,
+    "channels": 2,
+    "bitrate": "128 kbps",
+    "sha256": "ade69a48f4a5596869aba5c897ee1188f342849ac13f839147742b6177f8a428"
+  },
+  "loop": {
+    "asset": "AIClient/Assets/Bundles/Sound/BGM/MeadowBreeze_MainMenu_Loop.ogg",
+    "seconds": 84.0,
+    "sample_rate": 48000,
+    "channels": 2,
+    "bytes": 1408223,
+    "codec": "Vorbis",
+    "quality": 5,
+    "source_end_seconds": 86.0,
+    "crossfade_seconds": 2.0,
+    "crossfade_planned_bars": 1.0,
+    "target_rms_dbfs": -24.0,
+    "gain_db": -7.9607079788981,
+    "decoded_peak_dbfs": -9.168137550354004,
+    "decoded_rms_dbfs": -24.003089904785156,
+    "boundary_sample_delta": 0.0026645082980394363,
+    "internal_sample_delta_p99": 0.014939721673727036,
+    "sha256": "ce19b4f816656e8ce523c5b165527dcd90ddac8bd8eed9ce3a402fa018b19bdf"
+  },
+  "verification": {
+    "decode": "passed",
+    "finite_samples": true,
+    "clipping": false,
+    "musical_seam": "Cyclic crossfade applied; human listening review pending",
+    "runtime_playback": "Not wired; resource generation/import only"
+  }
+}
@@ -0,0 +1,16 @@
+{
+  "selected": "Assets/Bundles/Sound/BGM/MeadowBreeze_MainMenu_Loop.ogg",
+  "prefab": "Assets/Bundles/Sound/Prefab/MainMenuMusic.prefab",
+  "address": "MainMenuMusic",
+  "package": "Art",
+  "group": "Sound",
+  "loop": true,
+  "volume": 1.0,
+  "seconds": 84.0,
+  "channels": 2,
+  "frequency": 48000,
+  "independentMusicToggle": true,
+  "runtimePlaybackWired": true,
+  "bundleBuilt": false,
+  "verifiedUtc": "2026-10-20T10:44:17.1910890Z"
+}
@@ -0,0 +1,16 @@
+{
+  "result": "PASS",
+  "selected": "MeadowBreeze_MainMenu_Loop",
+  "length": 84.0,
+  "startup": true,
+  "settingsToggleCycles": 3,
+  "resumesWithoutRestart": true,
+  "independentSfxToggle": true,
+  "singlePlayer": true,
+  "pinballPauseAndReturn": true,
+  "gameplayGate": true,
+  "applicationPauseAndResume": true,
+  "loopWrap": true,
+  "preferencesRestoredInFinally": true,
+  "verifiedUtc": "2026-10-20T10:45:39.2147005Z"
+}
@@ -0,0 +1 @@
+Original instrumental main-menu music for a cozy pastoral fantasy game, with the tender, airy storytelling atmosphere of a hand-drawn Japanese animated feature: a quiet green village, small cream cottages, a little fountain, friendly animal companions, sunlight moving through leaves and a gentle breeze before a small adventure. Much softer and calmer than a bouncy casual-game tune. Slow, unhurried adagio feel, delicate and intimate, quietly hopeful with a trace of wistful wonder. Soft felted acoustic piano is the main voice, playing a simple lyrical original melody with long singing phrases, rests and light broken chords. A warm breathy flute or clarinet answers only occasionally; a small string ensemble holds very thin, soft sustained harmonies in the background, with a few quiet harp notes. Warm major-key colors, occasional gentle modal shading and spacious add9 or sixth chords, subtle natural room reverb, tender chamber-orchestra sound. Pianissimo to mezzo-piano throughout, soft rounded attacks, sparse notes, slow harmonic changes, plenty of silence between phrases, low density and no energetic pulse. No drums, no shaker, no woodblock, no busy pizzicato, no prominent marimba or xylophone, no bright music-box ostinato, no heavy bass, no sharp staccato, no heroic brass, no epic crescendo, no dramatic climax, no EDM or synth beat. Entirely instrumental: no singing, no humming, no choir, no spoken words, no environmental sound effects. A small original A-B-A theme with restrained variations, suitable for comfortable repeated listening beneath menu interactions. Keep the opening and final phrases in compatible harmony and texture, a brief gentle entrance, no long silent ending and no grand finale. Clean stereo acoustic film-score production. Compose an original melody, without quoting any existing film theme.
@@ -0,0 +1,20 @@
+{
+  "asset": "Assets/Bundles/Sound/BGM/MeadowBreeze_MainMenu_Loop.ogg",
+  "guid": "2011c89c89761724f99d1b8e865d5d54",
+  "length": 84.0,
+  "samples": 4032000,
+  "channels": 2,
+  "frequency": 48000,
+  "loadType": "CompressedInMemory",
+  "compression": "Vorbis",
+  "quality": 0.7,
+  "loadInBackground": true,
+  "preloadAudioData": false,
+  "package": "Art",
+  "group": "Sound",
+  "address": "MeadowBreeze_MainMenu_Loop",
+  "packRule": "PackSeparately",
+  "runtimePlaybackWired": false,
+  "bundleBuilt": false,
+  "verifiedUtc": "2026-10-20T10:02:21.7320431Z"
+}
				`@@ -0,0 +1 @@`
				Original instrumental main-menu music for a cozy pastoral fantasy game, with the tender, airy storytelling atmosphere of a hand-drawn Japanese animated feature: a quiet green village, small cream cottages, a little fountain, friendly animal companions, sunlight moving through leaves and a gentle breeze before a small adventure. Much softer and calmer than a bouncy casual-game tune. Slow, unhurried adagio feel, delicate and intimate, quietly hopeful with a trace of wistful wonder. Soft felted acoustic piano is the main voice, playing a simple lyrical original melody with long singing phrases, rests and light broken chords. A warm breathy flute or clarinet answers only occasionally; a small string ensemble holds very thin, soft sustained harmonies in the background, with a few quiet harp notes. Warm major-key colors, occasional gentle modal shading and spacious add9 or sixth chords, subtle natural room reverb, tender chamber-orchestra sound. Pianissimo to mezzo-piano throughout, soft rounded attacks, sparse notes, slow harmonic changes, plenty of silence between phrases, low density and no energetic pulse. No drums, no shaker, no woodblock, no busy pizzicato, no prominent marimba or xylophone, no bright music-box ostinato, no heavy bass, no sharp staccato, no heroic brass, no epic crescendo, no dramatic climax, no EDM or synth beat. Entirely instrumental: no singing, no humming, no choir, no spoken words, no environmental sound effects. A small original A-B-A theme with restrained variations, suitable for comfortable repeated listening beneath menu interactions. Keep the opening and final phrases in compatible harmony and texture, a brief gentle entrance, no long silent ending and no grand finale. Clean stereo acoustic film-score production. Compose an original melody, without quoting any existing film theme.