feat: 添加 WebGAL 引擎描述文件规范实现 #858

A-kirami · 2026-02-05T11:03:36Z

🎯 PR 目的

实现 WebGAL 引擎描述文件规范（RFC v2.0），为引擎提供标准化的元数据描述，便于第三方工具识别和管理。

📦 主要变更

1. 新增引擎描述文件 (`webgal-engine.json`)

包含引擎的基本信息（名称、版本、类型）
提供多语言描述支持（中文、英文、日文）
包含作者信息、许可证、图标路径
提供相关链接（主页、仓库、文档、演示等）

2. 新增版本同步脚本 (`update-engine-version.js`)

自动从 package.json 读取版本号
同步更新 webgal-engine.json 中的 version 和 webgalVersion 字段
在构建前自动执行，确保版本一致性
提供友好的控制台输出

3. 修改构建流程

在 build 脚本中添加版本同步步骤
确保每次构建时引擎描述文件版本与 package.json 保持同步

🎨 设计亮点

自动化：版本号管理完全自动化，避免手动维护导致的不一致
标准化：遵循 RFC 规范，为生态系统提供统一的引擎识别标准
可扩展：描述文件支持多语言和自定义字段扩展
向后兼容：不影响现有功能，纯增量式改进

📚 相关文档

RFC 文档：RFC: WebGAL 定制引擎描述文件规范 (WebGAL Engine Manifest) #762

✅ 测试建议

运行 npm run build 验证版本同步脚本正常工作
检查构建后 webgal-engine.json 版本号是否正确更新
验证 JSON 文件格式正确性

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

fix: set logo background opaque when fade in

feat: preload template style files

feat: add ebg fading

feat: support conditional logic for string in -when command

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

fix: 修复 changeBg 与 changeFigure 的 exit 设置不能正常生效的问题

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

fix: resume alpha filter

fix: init config data when clear all data

…-comment fix: sentence save end-of-line comment

…omment feat: preserve inline comment in ISentence

fix: failed to modify source transform

feat: add blend mode argument

fix: update appreciation data properly

fix: ensure live2d blink focus in state is full

fix: voice volume OpenWebGAL#843

- 新增 webgal-engine.json 引擎描述文件，包含引擎元数据 - 新增 update-engine-version.js 脚本，自动同步版本号 - 修改构建流程，在构建前自动更新引擎描述文件版本 - 为第三方工具提供标准化的引擎识别和版本管理支持

gemini-code-assist · 2026-02-05T11:04:28Z

Summary of Changes

Hello @A-kirami, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

此拉取请求旨在通过引入 WebGAL 引擎描述文件规范（RFC v2.0）来提升引擎的标准化和可管理性。核心变更包括自动化版本同步机制，确保引擎元数据始终与项目版本保持一致；重构 UI 样式加载流程，利用缓存和事件机制优化性能；以及增强 PixiJS 渲染能力，支持更复杂的背景过渡动画和场景元素的混合模式与透明度控制。这些改进共同提升了引擎的开发效率、用户体验和生态系统的兼容性。

Highlights

引擎描述文件标准化: 引入 webgal-engine.json 文件，遵循 RFC v2.0 规范，提供引擎元数据（名称、版本、类型、多语言描述、作者、许可证、链接等），便于第三方工具识别和管理。
自动化版本同步: 新增 update-engine-version.js 脚本，在构建时自动将 package.json 中的版本号同步到 webgal-engine.json，确保版本一致性。
UI 样式加载优化: 重构 useApplyStyle 钩子，通过 WebGAL.styleObjects 缓存解析后的 SCSS 样式，并引入 afterStyleUpdate 事件，提升样式加载效率和灵活性。
背景切换动画增强: 改进背景切换逻辑，通过新增的 ebgOverlay 元素实现平滑的背景过渡动画，提升视觉体验。
PixiJS 渲染能力扩展: PixiStage 和 WebGALPixiContainer 增加了对 blendMode（混合模式）和 alphaFilterVal（透明度滤镜值）的支持，为场景元素提供更丰富的视觉表现力。
游戏数据持久化改进: 在解锁 BGM 和 CG 后立即保存用户数据，并优化了 resetAllData 逻辑，确保游戏配置在重置后能够正确恢复。
脚本解析器功能扩展: ISentence 接口新增 inlineComment 字段，允许在脚本语句中添加行内注释，提高脚本可读性。

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

packages/parser/package.json
- 版本号从 4.5.17 更新至 4.5.18。
packages/parser/src/interface/sceneInterface.ts
- ISentence 接口新增 inlineComment 字段，用于支持行内注释。
packages/parser/src/scriptParser/scriptParser.ts
- 更新脚本解析逻辑，初始化并处理 inlineComment 字段。
packages/webgal/index.html
- 在 body 样式中添加 background: black;。
- 新增 html-body__effect-background-overlay 元素及其样式，用于背景过渡效果。
packages/webgal/package.json
- 修改 build 脚本，在构建前执行 scripts/update-engine-version.js 脚本。
packages/webgal/public/webgal-engine.json
- 新增引擎描述文件，包含引擎名称、版本、类型、多语言描述、作者、许可证、图标和相关链接等元数据。
packages/webgal/scripts/update-engine-version.js
- 新增 Node.js 脚本，用于从 package.json 读取版本号并同步更新 webgal-engine.json 中的 version 和 webgalVersion 字段。
packages/webgal/src/Core/Modules/animationFunctions.ts
- 引入 stageActions。
- 修改 PixiStage.assignTransform 调用，新增 convertAlpha 参数。
- 在获取退出动画后，增加逻辑以移除对应的动画设置。
packages/webgal/src/Core/Modules/events.ts
- 新增 afterStyleUpdate 事件，用于在样式更新后触发。
packages/webgal/src/Core/controller/gamePlay/scriptExecutor.ts
- 改进 whenChecker 函数，使其在解析条件表达式时能正确处理字符串类型的变量，并进行引号包裹。
packages/webgal/src/Core/controller/scene/sceneInterface.ts
- ISentence 接口新增 inlineComment 字段。
packages/webgal/src/Core/controller/stage/pixi/PixiController.ts
- assignTransform 方法新增 convertAlpha 参数，并增加了对 alphaFilterVal 和 blendMode 的处理。
- 在添加人物立绘时，支持设置 blendMode。
packages/webgal/src/Core/controller/stage/pixi/WebGALPixiContainer.ts
- 引入 logger。
- 新增 alphaFilter 实例，并为其添加 alphaFilterVal 和 blendMode 的 getter/setter。
- 确保 alphaFilter 作为内部滤镜被添加到容器中。
packages/webgal/src/Core/controller/stage/pixi/animations/timeline.ts
- 移除关于 alphaFilterVal 的注释。
packages/webgal/src/Core/controller/stage/pixi/animations/universalSoftIn.ts
- 软入动画逻辑更新，使用 alphaFilterVal 而非 alpha 属性来控制透明度。
packages/webgal/src/Core/controller/stage/pixi/animations/universalSoftOff.ts
- 软出动画逻辑更新，使用 alphaFilterVal 而非 alpha 属性来控制透明度。
packages/webgal/src/Core/gameScripts/bgm.ts
- 引入 localforage 和 WebGAL。
- 在解锁 BGM 后立即保存用户数据。
packages/webgal/src/Core/gameScripts/changeBg/index.ts
- 引入 localforage。
- 在解锁 CG 后立即保存用户数据。
packages/webgal/src/Core/gameScripts/changeBg/setEbg.ts
- 重构 setEbg 函数，利用 ebgOverlay 实现背景图的平滑过渡动画，并支持设置动画时长。
packages/webgal/src/Core/gameScripts/changeFigure.ts
- changeFigure 函数新增 blendMode 参数。
- 增加逻辑避免在关闭立绘时设置动画名称。
- 在设置人物立绘元数据时，支持 blendMode。
packages/webgal/src/Core/gameScripts/choose/index.tsx
- useApplyStyle 调用方式更新，使用 UI 键名而非完整路径。
packages/webgal/src/Core/gameScripts/setVar.ts
- getValueFromStateElseKey 函数新增 quoteString 参数，用于在需要时对字符串结果进行引号包裹。
packages/webgal/src/Core/util/coreInitialFunction/infoFetcher.ts
- 引入 setUserData 和 IGameVar。
- 在初始化时，存储 config.txt 中的游戏配置到 gameConfigInit，以便后续数据重置。
packages/webgal/src/Core/util/coreInitialFunction/templateLoader.ts
- 引入 scss2cssinjsParser 和 injectGlobal。
- 新增 loadStyleFiles 函数，用于加载并解析模板样式文件，并将结果存储到 WebGAL.styleObjects。
- 注册 afterStyleUpdate 事件。
packages/webgal/src/Core/webgalCore.ts
- 引入 IWebGALStyleObj。
- WebgalCore 类新增 styleObjects Map，用于缓存解析后的样式对象。
packages/webgal/src/Stage/AudioContainer/AudioContainer.tsx
- 修正 vocal 音量计算逻辑。
- useEffect 钩子中添加 stageStore.playVocal 作为依赖项。
packages/webgal/src/Stage/MainStage/useSetBg.ts
- 调整 setEbg 函数的调用时机，传入动画时长参数。
packages/webgal/src/Stage/MainStage/useSetFigure.ts
- 更新 useSetFigure 钩子，使其能够根据 figureMetaData 中的 blendMode 更新人物立绘的混合模式。
packages/webgal/src/Stage/TextBox/IMSSTextbox.tsx
- useApplyStyle 调用方式更新，使用 UI 键名而非完整路径。
packages/webgal/src/UI/Logo/logo.module.scss
- 调整 logo 动画的 opacity 关键帧，增加 65% 处的 opacity: 1。
packages/webgal/src/UI/Title/Title.tsx
- useApplyStyle 调用方式更新，使用 UI 键名而非完整路径。
packages/webgal/src/hooks/useApplyStyle.ts
- 重构 useApplyStyle 钩子，不再直接从文件加载 SCSS，而是从 WebGAL.styleObjects 获取缓存的样式对象。
- 注册 afterStyleUpdate 事件以响应样式更新。
packages/webgal/src/store/stageInterface.ts
- IFigureMetadata 接口新增 blendMode 字段。
packages/webgal/src/store/stageReducer.ts
- 引入 Live2D 基础参数。
- 改进 removeAnimationSettingsByTarget 逻辑，确保在移除动画设置时，如果存在退出动画，则保留一个 -off 的设置。
- 新增 removeAnimationSettingsByTargetOff action。
- 在设置 Live2D 的 blink 和 focus 时，确保使用完整的默认参数。
packages/webgal/src/store/userDataInterface.ts
- IUserData 接口新增 gameConfigInit 字段。
packages/webgal/src/store/userDataReducer.ts
- initState 中初始化 gameConfigInit。
- 更新 unlockCgInUserData 和 unlockBgmInUserData，使其在解锁时设置 name 字段。
- 修改 resetAllData 逻辑，在重置所有数据时，保留并恢复 gameConfigInit 和 globalGameVar。

Activity

A-kirami 创建了此拉取请求，旨在实现 WebGAL 引擎描述文件规范并优化相关功能。
A-kirami 提交了多项代码变更，包括新增引擎描述文件、版本同步脚本、UI 样式加载重构、PixiJS 渲染增强以及游戏数据持久化改进。

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

本次 PR 实现了 WebGAL 引擎描述文件规范，并引入了版本自动同步脚本，这是一个很棒的标准化改进。同时，PR 还包含了大量的功能增强、重构和 Bug 修复，显著提升了代码质量和健壮性。

主要亮点包括：

新功能: 添加了 webgal-engine.json 规范、立绘混合模式（blend mode）支持和脚本行内注释。
重构: 对 PIXI 对象的 Alpha 处理和 useApplyStyle hook 进行了重构，使样式加载更集中、高效。
改进: 背景切换增加了交叉淡入淡出效果，resetAllData 现在会保留初始游戏配置，Live2D 相关 Reducer 的逻辑更健壮。
修复: 修正了 when 条件解析、资源解锁逻辑等多个 Bug。

代码整体质量很高，改动考虑周全。我只发现了一个可以改进的小问题，即在解锁 CG/BGM 后保存用户数据时，没有处理潜在的异步错误。除此之外，其他改动都非常出色。

gemini-code-assist · 2026-02-05T11:06:35Z

packages/webgal/src/Core/gameScripts/bgm.ts

  if (name !== '') {
    webgalStore.dispatch(unlockBgmInUserData({ name, url, series }));
+    const userDataState = webgalStore.getState().userData;
+    localforage.setItem(WebGAL.gameKey, userDataState).then(() => {});


localforage.setItem 是一个异步操作，可能会失败。当前的 .then(() => {}) 写法会静默地忽略所有潜在的错误，导致在保存用户数据失败时开发者和用户都无法察觉。建议添加错误处理，以便在出现问题时能够记录日志。

Suggested change

localforage.setItem(WebGAL.gameKey, userDataState).then(() => {});

localforage.setItem(WebGAL.gameKey, userDataState).catch(error => logger.error('保存用户数据失败：', error));

gemini-code-assist · 2026-02-05T11:06:35Z

packages/webgal/src/Core/gameScripts/changeBg/index.ts

  if (unlockName !== '') {
    dispatch(unlockCgInUserData({ name: unlockName, url, series }));
+    const userDataState = webgalStore.getState().userData;
+    localforage.setItem(WebGAL.gameKey, userDataState).then(() => {});


localforage.setItem 是一个异步操作，可能会失败。当前的 .then(() => {}) 写法会静默地忽略所有潜在的错误，导致在保存用户数据失败时开发者和用户都无法察觉。建议添加错误处理，以便在出现问题时能够记录日志。

Suggested change

localforage.setItem(WebGAL.gameKey, userDataState).then(() => {});

localforage.setItem(WebGAL.gameKey, userDataState).catch(error => logger.error('保存用户数据失败：', error));

HardyNLee and others added 30 commits December 29, 2025 21:58

feat: add ebg fading

e77a256

fix: set logo background opaque when fade in

122f22c

feat: preload template style files

f7fc5e0

refactor: use promise all to load style files

0547dc5

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Merge pull request OpenWebGAL#824 from ChangeSuger/fix/logo

9b24bb6

fix: set logo background opaque when fade in

lint and add a todo check

17d43f2

Merge pull request OpenWebGAL#825 from HardyNLee/feat/preload-style

0162551

feat: preload template style files

Merge pull request OpenWebGAL#818 from HardyNLee/feat/ebg-fading

75f9683

feat: add ebg fading

feat: support conditional logic for string in -when command

903e316

add a trim to var name

e591cd9

Merge pull request OpenWebGAL#826 from ChangeSuger/feat/when-enhance

65dd43e

feat: support conditional logic for string in -when command

fix: 修复 changeBg 与 changeFigure 的 exit 设置不能正常生效的问题

f147480

feat: 应用退出动画后删除退出动画设定；立绘关闭时不设定动画

3f1611b

fix: init config data when clear all data

f61529d

Update packages/webgal/src/store/userDataReducer.ts

520d054

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Merge pull request OpenWebGAL#827 from ChangeSuger/fix/exit-animation

9d0a964

fix: 修复 changeBg 与 changeFigure 的 exit 设置不能正常生效的问题

feat: use global store to storage game config init

b7382cf

fix: sentence save end-of-line comment

6456087

fix: resume alpha filter

a42e102

chore: write to variable

3ce6e38

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Merge pull request OpenWebGAL#832 from HardyNLee/fix/resume-alpha-filter

f159ed6

fix: resume alpha filter

Merge pull request OpenWebGAL#828 from ChangeSuger/fix/config-data-clear

c6c6663

fix: init config data when clear all data

Merge pull request OpenWebGAL#834 from xiaoxustudio/fix/sentence-line…

2441914

…-comment fix: sentence save end-of-line comment

feat: preserve inline comment in ISentence

b76453d

fix: update appreciation data properly

2d9495b

Merge pull request OpenWebGAL#836 from HardyNLee/feat/parser-inline-c…

0319b8d

…omment feat: preserve inline comment in ISentence

update parser version

7bcbd5d

fix: failed to modify source transform

298dead

Merge pull request OpenWebGAL#838 from HardyNLee/fix/read-only-source

5d963eb

fix: failed to modify source transform

feat: add blend mode argument

624db78

HardyNLee and others added 7 commits January 27, 2026 06:02

fix: ensure live2d blink focus in state is full

0e108a9

Merge pull request OpenWebGAL#844 from HardyNLee/feat/figure-blend-mode

ee8c6fe

feat: add blend mode argument

Merge pull request OpenWebGAL#839 from HardyNLee/fix/appreciation-data

b543d54

fix: update appreciation data properly

Merge pull request OpenWebGAL#845 from HardyNLee/fix/full-blink-focus

d0bfe83

fix: ensure live2d blink focus in state is full

fix: voice volume OpenWebGAL#843

e0ab2e4

Merge pull request OpenWebGAL#850 from OpenWebGAL/fix-say-volume

92f7543

fix: voice volume OpenWebGAL#843

gemini-code-assist bot reviewed Feb 5, 2026

View reviewed changes

A-kirami closed this Feb 5, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: 添加 WebGAL 引擎描述文件规范实现 #858

feat: 添加 WebGAL 引擎描述文件规范实现 #858

Uh oh!

A-kirami commented Feb 5, 2026

Uh oh!

gemini-code-assist bot commented Feb 5, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Feb 5, 2026

Uh oh!

gemini-code-assist bot Feb 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

	localforage.setItem(WebGAL.gameKey, userDataState).then(() => {});
	localforage.setItem(WebGAL.gameKey, userDataState).catch(error => logger.error('保存用户数据失败：', error));

Uh oh!

feat: 添加 WebGAL 引擎描述文件规范实现 #858

feat: 添加 WebGAL 引擎描述文件规范实现 #858

Uh oh!

Conversation

A-kirami commented Feb 5, 2026

🎯 PR 目的

📦 主要变更

1. 新增引擎描述文件 (webgal-engine.json)

2. 新增版本同步脚本 (update-engine-version.js)

3. 修改构建流程

🎨 设计亮点

📚 相关文档

✅ 测试建议

Uh oh!

gemini-code-assist bot commented Feb 5, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

1. 新增引擎描述文件 (`webgal-engine.json`)

2. 新增版本同步脚本 (`update-engine-version.js`)