阶段性完成

Assets/Scripts/NewStorySystem/YarnFunctions/StoryTreeCommands.cs

@@ -1,6 +1,7 @@
 using Ichni.Story.Dialogue;
 using Ichni.Story.UI;
-using Ichni.Localization;
+using Ichni.Menu;
+using System.Collections.Generic;
 using UnityEngine;
 using Yarn.Unity;
 
@@ -14,14 +15,17 @@ namespace Ichni.Story.YarnFunctions
         // ── Yarn Commands ────────────────────────────────────────────────────────
 
         /// <summary>
-        /// 兼容既有 Yarn 脚本：授予歌曲相关的解锁 Key，并在当前对话结束后弹出提示。
-        /// 格式: &lt;&lt;unlock_song unlock_key&gt;&gt;
+        /// 授予歌曲相关的解锁 Key，并在当前对话结束后弹出提示。
+        /// 格式: &lt;&lt;unlock_song unlock_key "song_id"&gt;&gt;
         /// <para>Key 必须使用小写字母、数字和下划线，例如 <c>story_ch0_prologue_completed</c>。</para>
+        /// <para><c>song_id</c> 必须是 <see cref="SongItemData.songName"/> 的稳定标识，而不是显示名称或本地化文本。
+        /// 该参数用于解析玩家可见的歌曲名称，绝不能将技术 Unlock Key 显示给玩家。</para>
         /// 新内容若不需要歌曲提示，优先使用 <see cref="GrantUnlock"/>。
         /// </summary>
         /// <param name="songUnlockKey">要授予的稳定解锁 Key，而不是歌曲显示名称。</param>
+        /// <param name="songId">对应 <see cref="SongItemData.songName"/> 的稳定歌曲 ID。</param>
         [YarnCommand("unlock_song")]
-        public static void UnlockSong(string songUnlockKey)
+        public static void UnlockSong(string songUnlockKey, string songId)
         {
             ExecuteAfterDialogueCommit(() =>
             {
@@ -31,7 +35,7 @@ namespace Ichni.Story.YarnFunctions
                 }
 
                 if (MessageUIPage.instance != null)
-                    MessageUIPage.instance.ShowUnlockMessage(songUnlockKey);
+                    MessageUIPage.instance.ShowUnlockMessage(ResolveSongDisplayName(songId));
                 else
                     Debug.LogError("[StoryTreeCommands] 弹窗失败：场景中未找到 StoryMessageBoxUIPage 实例！");
 
@@ -57,7 +61,7 @@ namespace Ichni.Story.YarnFunctions
 
         /// <summary>
         /// 在对话结束后，弹出一个自定义 MessageBox 提示。
-        /// 会尝试使用 Unity Localization 进行翻译，如果找不到对应条目则回退显示原文本（Key）。
+        /// 文本 Key 会交给 MessageUIPage 的 FIFO 队列，并在该弹窗真正显示前才按当前 Locale 解析。
         /// 格式: &lt;&lt;show_message titleKey contentKey [tableName]&gt;&gt;
         /// </summary>
         /// <param name="titleKey">标题文本或本地化键</param>
@@ -66,13 +70,13 @@ namespace Ichni.Story.YarnFunctions
         [YarnCommand("show_message")]
         public static void ShowMessage(string titleKey, string contentKey, string tableName = "Message")
         {
-            string translatedTitle = GetTranslatedText(tableName, titleKey);
-            string translatedContent = GetTranslatedText(tableName, contentKey);
-            Debug.Log($"[StoryTreeCommands] 准备在对话结束后显示自定义弹窗：标题='{translatedTitle}'，内容='{translatedContent}'");
+            Debug.Log($"[StoryTreeCommands] 准备在对话结束后显示本地化弹窗：Table='{tableName}'，TitleKey='{titleKey}'，ContentKey='{contentKey}'。");
             ExecuteAfterDialogueCommit(() =>
             {
                 if (MessageUIPage.instance != null)
-                    MessageUIPage.instance.ShowCustomMessage(translatedTitle, translatedContent);
+                    MessageUIPage.instance.ShowLocalizedMessage(
+                        new LocalizedPopupText(tableName, titleKey),
+                        new LocalizedPopupText(tableName, contentKey));
                 else
                     Debug.LogError("[StoryTreeCommands] 无法显示自定义弹窗：未找到 MessageUIPage 实例。");
             });
@@ -128,9 +132,36 @@ namespace Ichni.Story.YarnFunctions
 
         // ── 内部辅助 ─────────────────────────────────────────────────────────────
 
-        private static string GetTranslatedText(string tableName, string key)
+        /// <summary>
+        /// 以稳定 Song ID 查找当前项目中配置的歌曲显示名。当前阶段使用 <see cref="SongItemData.displaySongName"/>；
+        /// 将来歌曲标题接入 Chapter Content 本地化后，只需替换本函数内部的返回逻辑，Yarn 与弹窗 API 无需修改。
+        /// </summary>
+        private static string ResolveSongDisplayName(string songId)
         {
-            return LocalizationTextService.Resolve(tableName, key, key);
+            List<ChapterSelectionUnit> chapters = ChapterSelectionManager.instance?.chapters;
+            if (chapters != null)
+            {
+                foreach (ChapterSelectionUnit chapter in chapters)
+                {
+                    if (chapter?.songs == null)
+                    {
+                        continue;
+                    }
+
+                    foreach (SongItemData song in chapter.songs)
+                    {
+                        if (song != null && song.songName == songId)
+                        {
+                            return string.IsNullOrWhiteSpace(song.displaySongName)
+                                ? song.songName
+                                : song.displaySongName;
+                        }
+                    }
+                }
+            }
+
+            Debug.LogWarning($"[StoryTreeCommands] 无法为歌曲解锁提示解析 Song ID '{songId}'，将显示该 ID。", ChapterSelectionManager.instance);
+            return songId ?? string.Empty;
         }
     }
 }