webgal-parser 4.6.2 → 4.6.3-beta.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # WebGAL Parser Changelog
 
+## [4.6.3-beta.2] - 2026-07-31
+
+### Fixed
+- `sceneTextPreProcess`：折叠序列的首行是空行时（例如空行后面紧跟一条续行），整条序列会被静默丢弃，导致预处理后行数变少。这会击穿「解析后语句 index == 文件行号」，进而让存档进度错位。改用 `null` 哨兵区分「不在折叠序列中」与「首行内容为空串」
+
+## [4.6.3-beta.1] - 2026-07-31
+
+### Added
+- 正式启用多行语句支持：`sceneParser` 现在会先经过 `sceneTextPreProcess`，把以空白开头且首字符为 `-` 或 `|` 的续行折叠进上一条语句
+- `ISentence` 新增行范围字段 `startLine` / `endLine`（0-based，含首尾）与 `isLineBreakHolder`，供图形编辑器按行范围整体替换语句
+- 导出 `WEBGAL_LINE_BREAK_MARK` 与 `isLineBreakPlaceholder`
+
+### Fixed
+- `sceneTextPreProcess`：移除逐行 `console.log`；场景首行不再被误判为续行；场景末行以 `\` 结尾时不再丢失整段累积内容
+
+### Technical Notes
+- 续行会被替换成 `;_WEBGAL_LINE_BREAK_` 占位注释行，**预处理前后行数严格一致**。因此「解析后语句 index == 文件行号」这一不变量继续成立，引擎的存读档、Backlog、场景栈、已读记录（都存语句 index）无需改动，旧存档也不会错位
+
 ## [4.5.13] - 2025-07-05
 
 ### Fixed

package/build/cjs/index.cjs

@@ -39,6 +39,7 @@ var commandType;
     commandType[commandType["applyStyle"] = 32] = "applyStyle";
     commandType[commandType["wait"] = 33] = "wait";
     commandType[commandType["callSteam"] = 34] = "callSteam";
+    commandType[commandType["return"] = 35] = "return";
 })(commandType || (commandType = {}));
 
 const SCRIPT_CONFIG = [
@@ -80,6 +81,7 @@ const SCRIPT_CONFIG = [
     { scriptString: 'applyStyle', scriptType: commandType.applyStyle },
     { scriptString: 'wait', scriptType: commandType.wait },
     { scriptString: 'callSteam', scriptType: commandType.callSteam },
+    { scriptString: 'return', scriptType: commandType.return },
 ];
 const ADD_NEXT_ARG_LIST = [
     commandType.bgm,
@@ -138,7 +140,7 @@ function argsParser(argsRaw, assetSetter) {
             argValue = undefined;
         }
         // 判断是不是语音参数
-        if (argName.toLowerCase().match(/.ogg|.mp3|.wav/)) {
+        if (argName.toLowerCase().match(/.ogg|.mp3|.wav|.opus/)) {
             returnArrayList.push({
                 key: 'vocal',
                 value: assetSetter(e, fileType.vocal),
@@ -463,7 +465,10 @@ const scriptParser = (sentenceRaw, assetSetter, ADD_NEXT_ARG_LIST, SCRIPT_CONFIG
             args: [{ key: 'next', value: true }],
             sentenceAssets: [],
             subScene: [],
-            inlineComment: '', // 行内注释
+            inlineComment: '',
+            startLine: lineNumber,
+            endLine: lineNumber,
+            isLineBreakHolder: false,
         };
     }
     // 截取命令
@@ -514,92 +519,14 @@ const scriptParser = (sentenceRaw, assetSetter, ADD_NEXT_ARG_LIST, SCRIPT_CONFIG
         args: args,
         sentenceAssets: sentenceAssets,
         subScene: subScene,
-        inlineComment: sentenceComment.trim(), // 行内注释
+        inlineComment: sentenceComment.trim(),
+        // 单行语句的行范围就是自己，多行语句的 endLine 由 sceneParser 回填
+        startLine: lineNumber,
+        endLine: lineNumber,
+        isLineBreakHolder: false,
     };
 };
 
-/**
- * 场景解析器
- * @param rawScene 原始场景
- * @param sceneName 场景名称
- * @param sceneUrl 场景url
- * @param assetsPrefetcher
- * @param assetSetter
- * @param ADD_NEXT_ARG_LIST
- * @param SCRIPT_CONFIG_MAP
- * @return {IScene} 解析后的场景
- */
-const sceneParser = (rawScene, sceneName, sceneUrl, assetsPrefetcher, assetSetter, ADD_NEXT_ARG_LIST, SCRIPT_CONFIG_MAP) => {
-    const rawSentenceList = rawScene.replaceAll('\r', '').split('\n'); // 原始句子列表
-    // 去分号留到后面去做了，现在注释要单独处理
-    const rawSentenceListWithoutEmpty = rawSentenceList;
-    // .map((sentence) => sentence.split(";")[0])
-    // .filter((sentence) => sentence.trim() !== "");
-    let assetsList = []; // 场景资源列表
-    let subSceneList = []; // 子场景列表
-    const sentenceList = rawSentenceListWithoutEmpty.map((sentence, index) => {
-        const returnSentence = scriptParser(sentence, assetSetter, ADD_NEXT_ARG_LIST, SCRIPT_CONFIG_MAP, index);
-        // 在这里解析出语句可能携带的资源和场景，合并到 assetsList 和 subSceneList
-        assetsList = [...assetsList, ...returnSentence.sentenceAssets];
-        subSceneList = [...subSceneList, ...returnSentence.subScene];
-        return returnSentence;
-    });
-    // 开始资源的预加载
-    assetsList = deduplicateAssets(assetsList);
-    assetsPrefetcher(assetsList);
-    return {
-        sceneName: sceneName,
-        sceneUrl: sceneUrl,
-        sentenceList: sentenceList,
-        assetsList: assetsList,
-        subSceneList: subSceneList, // 子场景列表
-    };
-};
-const deduplicateAssets = (assetsList) => {
-    const seenAssets = new Set();
-    return assetsList.filter((asset) => {
-        if (!asset || typeof asset.url !== 'string' || asset.url === '') {
-            return false;
-        }
-        const assetKey = `${asset.type}:${asset.url}`;
-        if (seenAssets.has(assetKey)) {
-            return false;
-        }
-        seenAssets.add(assetKey);
-        return true;
-    });
-};
-
-function scss2cssinjsParser(scssString) {
-    const [classNameStyles, others] = parseCSS(scssString);
-    return {
-        classNameStyles,
-        others,
-    };
-}
-/**
- * GPT 4 写的，临时用，以后要重构！！！
- * TODO：用人类智能重构，要是用着一直没问题，也不是不可以 trust AI
- * @param css
- */
-function parseCSS(css) {
-    const result = {};
-    let specialRules = '';
-    let matches;
-    // 使用非贪婪匹配，尝试正确处理任意层次的嵌套
-    const classRegex = /\.([^{\s]+)\s*{((?:[^{}]*|{[^}]*})*)}/g;
-    const specialRegex = /(@[^{]+{\s*(?:[^{}]*{[^}]*}[^{}]*)+\s*})/g;
-    while ((matches = classRegex.exec(css)) !== null) {
-        const key = matches[1];
-        const value = matches[2].trim().replace(/\s*;\s*/g, ';\n');
-        result[key] = value;
-    }
-    while ((matches = specialRegex.exec(css)) !== null) {
-        specialRules += matches[1].trim() + '\n';
-    }
-    return [result, specialRules.trim()];
-}
-
 /**
  * Preprocessor for scene text.
  *
@@ -629,13 +556,11 @@ function sceneTextPreProcessPassOne(lines) {
     let lastLineIsMultiline = false;
     let thisLineIsMultiline = false;
     for (const line of lines) {
-        thisLineIsMultiline = false;
-        if (canBeMultiline(line)) {
-            thisLineIsMultiline = true;
-        }
-        if (shouldNotBeMultiline(line, lastLineIsMultiline)) {
-            thisLineIsMultiline = false;
-        }
+        // 续行需要接到上一行，所以场景的第一行永远不会是续行。
+        thisLineIsMultiline =
+            processedLines.length > 0 &&
+                canBeMultiline(line) &&
+                !shouldNotBeMultiline(line, lastLineIsMultiline);
         if (thisLineIsMultiline) {
             processedLines[processedLines.length - 1] += '\\';
         }
@@ -682,7 +607,10 @@ function isEmptyLine(line) {
  */
 function sceneTextPreProcessPassTwo(lines) {
     const processedLines = [];
-    let currentMultilineContent = "";
+    // null 表示当前不在多行序列里。这里不能用空串来判断：
+    // 序列的首行本身可能就是空行（比如空行后面紧跟着一条续行），
+    // 那样整条序列会被静默丢弃，破坏「预处理前后行数一致」这个前提。
+    let currentMultilineContent = null;
     let placeHolderLines = [];
     function concat(line) {
         let trimmed = line.trim();
@@ -692,11 +620,16 @@ function sceneTextPreProcessPassTwo(lines) {
         currentMultilineContent = currentMultilineContent + trimmed;
         placeHolderLines.push(placeholderLine(line));
     }
+    /** 把折叠好的整条语句连同补齐行数的占位行一起输出 */
+    function flushMultiline() {
+        processedLines.push(currentMultilineContent, ...placeHolderLines);
+        placeHolderLines = [];
+        currentMultilineContent = null;
+    }
     for (const line of lines) {
-        console.log(line);
         if (line.endsWith('\\')) {
             const trueLine = line.slice(0, -1);
-            if (currentMultilineContent === "") {
+            if (currentMultilineContent === null) {
                 // first line
                 currentMultilineContent = trueLine;
             }
@@ -706,19 +639,32 @@ function sceneTextPreProcessPassTwo(lines) {
             }
             continue;
         }
-        if (currentMultilineContent !== "") {
+        if (currentMultilineContent !== null) {
             // end line
             concat(line);
-            processedLines.push(currentMultilineContent);
-            processedLines.push(...placeHolderLines);
-            placeHolderLines = [];
-            currentMultilineContent = "";
+            flushMultiline();
             continue;
         }
         processedLines.push(line);
     }
+    // 场景末行仍以 \ 结尾时循环里没有机会收尾，在这里把累积的内容补出去。
+    if (currentMultilineContent !== null) {
+        flushMultiline();
+    }
     return processedLines;
 }
+/**
+ * 占位行的前缀。占位行本身是一条注释，引擎会空跑掉；
+ * 它的作用是让预处理后的行数与原始场景一致，从而保持
+ * 「解析后语句 index == 文件行号」这一不变量。
+ */
+const WEBGAL_LINE_BREAK_MARK = ';_WEBGAL_LINE_BREAK_';
+/**
+ * 判断预处理后的某一行是否是占位行，即它是上一条多行语句折叠掉的续行。
+ */
+function isLineBreakPlaceholder(processedLine) {
+    return processedLine.startsWith(WEBGAL_LINE_BREAK_MARK);
+}
 /**
  * Placeholder Line. Adding this line preserves the original number of lines
  * in the scene text, so that it can be compatible with the graphical editor.
@@ -727,70 +673,116 @@ function sceneTextPreProcessPassTwo(lines) {
  * @returns The placeholder line
  */
 function placeholderLine(content = "") {
-    return ";_WEBGAL_LINE_BREAK_" + content;
+    return WEBGAL_LINE_BREAK_MARK + content;
+}
+
+/**
+ * 场景解析器
+ * @param rawScene 原始场景
+ * @param sceneName 场景名称
+ * @param sceneUrl 场景url
+ * @param assetsPrefetcher
+ * @param assetSetter
+ * @param ADD_NEXT_ARG_LIST
+ * @param SCRIPT_CONFIG_MAP
+ * @return {IScene} 解析后的场景
+ */
+const sceneParser = (rawScene, sceneName, sceneUrl, assetsPrefetcher, assetSetter, ADD_NEXT_ARG_LIST, SCRIPT_CONFIG_MAP) => {
+    // 预处理把多行语句折叠进它的首行，并用占位行补齐被折叠掉的行，
+    // 因此这里的行数与原始场景严格一致，「语句 index == 文件行号」始终成立。
+    const rawSentenceList = sceneTextPreProcess(rawScene).split('\n'); // 原始句子列表
+    // 去分号留到后面去做了，现在注释要单独处理
+    const rawSentenceListWithoutEmpty = rawSentenceList;
+    // .map((sentence) => sentence.split(";")[0])
+    // .filter((sentence) => sentence.trim() !== "");
+    let assetsList = []; // 场景资源列表
+    let subSceneList = []; // 子场景列表
+    const sentenceList = rawSentenceListWithoutEmpty.map((sentence, index) => {
+        const returnSentence = scriptParser(sentence, assetSetter, ADD_NEXT_ARG_LIST, SCRIPT_CONFIG_MAP, index);
+        // 在这里解析出语句可能携带的资源和场景，合并到 assetsList 和 subSceneList
+        assetsList = [...assetsList, ...returnSentence.sentenceAssets];
+        subSceneList = [...subSceneList, ...returnSentence.subScene];
+        return returnSentence;
+    });
+    markMultilineRanges(sentenceList, rawSentenceList);
+    // 开始资源的预加载
+    assetsList = deduplicateAssets(assetsList);
+    assetsPrefetcher(assetsList);
+    return {
+        sceneName: sceneName,
+        sceneUrl: sceneUrl,
+        sentenceList: sentenceList,
+        assetsList: assetsList,
+        subSceneList: subSceneList, // 子场景列表
+    };
+};
+/**
+ * 回填多行语句的行范围。
+ *
+ * 预处理后，一条多行语句的完整内容都落在它的首行，紧跟其后的若干占位行
+ * 就是被折叠掉的续行。这里把占位行标记出来，并把首行语句的 endLine
+ * 推到最后一条续行，图形编辑器据此按整个行范围替换语句。
+ *
+ * @param sentenceList 解析后的语句列表
+ * @param processedLines 预处理后的行，与 sentenceList 一一对应
+ */
+const markMultilineRanges = (sentenceList, processedLines) => {
+    let headIndex = -1; // 最近一条非占位语句的下标，即当前多行语句的首行
+    for (let index = 0; index < sentenceList.length; index++) {
+        if (!isLineBreakPlaceholder(processedLines[index])) {
+            headIndex = index;
+            continue;
+        }
+        sentenceList[index].isLineBreakHolder = true;
+        if (headIndex >= 0) {
+            sentenceList[headIndex].endLine = index;
+        }
+    }
+};
+const deduplicateAssets = (assetsList) => {
+    const seenAssets = new Set();
+    return assetsList.filter((asset) => {
+        if (!asset || typeof asset.url !== 'string' || asset.url === '') {
+            return false;
+        }
+        const assetKey = `${asset.type}:${asset.url}`;
+        if (seenAssets.has(assetKey)) {
+            return false;
+        }
+        seenAssets.add(assetKey);
+        return true;
+    });
+};
+
+function scss2cssinjsParser(scssString) {
+    const [classNameStyles, others] = parseCSS(scssString);
+    return {
+        classNameStyles,
+        others,
+    };
 }
-// export function sceneTextPreProcess(sceneText: string): string {
-//   const lines = sceneText.replaceAll('\r', '').split('\n');
-//   const processedLines: string[] = [];
-//   let lastNonMultilineIndex = -1;
-//   let isInMultilineSequence = false;
-//   function isMultiline(line: string): boolean {
-//     if (!line.startsWith(' ')) return false;
-//     const trimmedLine = line.trimStart();
-//     return trimmedLine.startsWith('|') || trimmedLine.startsWith('-');
-//   }
-//   for (let i = 0; i < lines.length; i++) {
-//     const line = lines[i];
-//     if (line.trim() === '') {
-//       // Empty line handling
-//       if (isInMultilineSequence) {
-//         // Check if the next line is a multiline line
-//         let isStillInMulti = false;
-//         for (let j = i + 1; j < lines.length; j++) {
-//           const lookForwardLine = lines[j] || '';
-//           // 遇到正常语句了，直接中断
-//           if (lookForwardLine.trim() !== '' && !isMultiline(lookForwardLine)) {
-//             isStillInMulti = false;
-//             break;
-//           }
-//           // 必须找到后面接的是参数，并且中间没有遇到任何正常语句才行
-//           if (lookForwardLine.trim() !== '' && isMultiline(lookForwardLine)) {
-//             isStillInMulti = true;
-//             break;
-//           }
-//         }
-//         if (isStillInMulti) {
-//           // Still within a multiline sequence
-//           processedLines.push(';_WEBGAL_LINE_BREAK_');
-//         } else {
-//           // End of multiline sequence
-//           isInMultilineSequence = false;
-//           processedLines.push(line);
-//         }
-//       } else {
-//         // Preserve empty lines outside of multiline sequences
-//         processedLines.push(line);
-//       }
-//     } else if (isMultiline(line)) {
-//       // Multiline statement handling
-//       if (lastNonMultilineIndex >= 0) {
-//         // Concatenate to the previous non-multiline statement
-//         const trimedLine = line.trimStart();
-//         const addBlank = trimedLine.startsWith('-') ? ' ' : '';
-//         processedLines[lastNonMultilineIndex] += addBlank + trimedLine;
-//       }
-//       // Add the special comment line
-//       processedLines.push(';_WEBGAL_LINE_BREAK_' + line);
-//       isInMultilineSequence = true;
-//     } else {
-//       // Non-multiline statement handling
-//       processedLines.push(line);
-//       lastNonMultilineIndex = processedLines.length - 1;
-//       isInMultilineSequence = false;
-//     }
-//   }
-//   return processedLines.join('\n');
-// }
+/**
+ * GPT 4 写的，临时用，以后要重构！！！
+ * TODO：用人类智能重构，要是用着一直没问题，也不是不可以 trust AI
+ * @param css
+ */
+function parseCSS(css) {
+    const result = {};
+    let specialRules = '';
+    let matches;
+    // 使用非贪婪匹配，尝试正确处理任意层次的嵌套
+    const classRegex = /\.([^{\s]+)\s*{((?:[^{}]*|{[^}]*})*)}/g;
+    const specialRegex = /(@[^{]+{\s*(?:[^{}]*{[^}]*}[^{}]*)+\s*})/g;
+    while ((matches = classRegex.exec(css)) !== null) {
+        const key = matches[1];
+        const value = matches[2].trim().replace(/\s*;\s*/g, ';\n');
+        result[key] = value;
+    }
+    while ((matches = specialRegex.exec(css)) !== null) {
+        specialRules += matches[1].trim() + '\n';
+    }
+    return [result, specialRules.trim()];
+}
 
 class SceneParser {
     assetsPrefetcher;
@@ -837,5 +829,7 @@ class SceneParser {
 
 exports.ADD_NEXT_ARG_LIST = ADD_NEXT_ARG_LIST;
 exports.SCRIPT_CONFIG = SCRIPT_CONFIG;
+exports.WEBGAL_LINE_BREAK_MARK = WEBGAL_LINE_BREAK_MARK;
 exports.default = SceneParser;
+exports.isLineBreakPlaceholder = isLineBreakPlaceholder;
 exports.sceneTextPreProcess = sceneTextPreProcess;

package/build/cjs/index.d.ts

@@ -3,7 +3,7 @@ import { WebgalConfig } from './configParser/configParser';
 import { fileType } from './interface/assets';
 import { IAsset } from './interface/sceneInterface';
 import { IWebGALStyleObj } from "./styleParser";
-import { sceneTextPreProcess } from "./sceneTextPreProcessor";
+import { isLineBreakPlaceholder, sceneTextPreProcess, WEBGAL_LINE_BREAK_MARK } from "./sceneTextPreProcessor";
 export default class SceneParser {
     private readonly assetsPrefetcher;
     private readonly assetSetter;
@@ -23,4 +23,4 @@ export default class SceneParser {
     parseScssToWebgalStyleObj(scssString: string): IWebGALStyleObj;
 }
 export { ADD_NEXT_ARG_LIST, SCRIPT_CONFIG };
-export { sceneTextPreProcess };
+export { sceneTextPreProcess, isLineBreakPlaceholder, WEBGAL_LINE_BREAK_MARK };

package/build/cjs/interface/runtimeInterface.d.ts

@@ -6,6 +6,8 @@ export interface sceneEntry {
     sceneName: string;
     sceneUrl: string;
     continueLine: number;
+    locals?: Record<string, any>;
+    writeReturnTo?: string;
 }
 /**
  * 场景栈条目接口 (兼容性别名)

package/build/cjs/interface/sceneInterface.d.ts

@@ -38,7 +38,8 @@ export declare enum commandType {
     getUserInput = 31,
     applyStyle = 32,
     wait = 33,
-    callSteam = 34
+    callSteam = 34,
+    return = 35
 }
 /**
  * 单个参数接口
@@ -70,6 +71,15 @@ export interface ISentence {
     sentenceAssets: Array<IAsset>;
     subScene: Array<string>;
     inlineComment: string;
+    /**
+     * 本语句在原始场景文件中占据的行范围（0-based，含首尾）。
+     * 单行语句 startLine === endLine；多行语句 endLine 指向最后一条续行。
+     * 图形编辑器据此做「只替换被编辑语句所占的行」。
+     */
+    startLine: number;
+    endLine: number;
+    /** 本条是多行语句被折叠掉的续行占位，仅用于补齐行数，不应展示给用户 */
+    isLineBreakHolder: boolean;
 }
 /**
  * 场景接口

package/build/cjs/sceneTextPreProcessor.d.ts

@@ -9,3 +9,13 @@
  * @returns The processed scene text
  */
 export declare function sceneTextPreProcess(sceneText: string): string;
+/**
+ * 占位行的前缀。占位行本身是一条注释，引擎会空跑掉；
+ * 它的作用是让预处理后的行数与原始场景一致，从而保持
+ * 「解析后语句 index == 文件行号」这一不变量。
+ */
+export declare const WEBGAL_LINE_BREAK_MARK = ";_WEBGAL_LINE_BREAK_";
+/**
+ * 判断预处理后的某一行是否是占位行，即它是上一条多行语句折叠掉的续行。
+ */
+export declare function isLineBreakPlaceholder(processedLine: string): boolean;

package/build/es/index.d.ts

@@ -3,7 +3,7 @@ import { WebgalConfig } from './configParser/configParser';
 import { fileType } from './interface/assets';
 import { IAsset } from './interface/sceneInterface';
 import { IWebGALStyleObj } from "./styleParser";
-import { sceneTextPreProcess } from "./sceneTextPreProcessor";
+import { isLineBreakPlaceholder, sceneTextPreProcess, WEBGAL_LINE_BREAK_MARK } from "./sceneTextPreProcessor";
 export default class SceneParser {
     private readonly assetsPrefetcher;
     private readonly assetSetter;
@@ -23,4 +23,4 @@ export default class SceneParser {
     parseScssToWebgalStyleObj(scssString: string): IWebGALStyleObj;
 }
 export { ADD_NEXT_ARG_LIST, SCRIPT_CONFIG };
-export { sceneTextPreProcess };
+export { sceneTextPreProcess, isLineBreakPlaceholder, WEBGAL_LINE_BREAK_MARK };