mod_effects_base/docs/zh.md

Effects Engine — 场景的动态视觉特效

Effects Engine 让剧本能在场景上播放一段短小的视觉特效：闪光、烟雾、火花、魔法光晕。特效是一个小的 Godot 场景，由模组放在自己的 effects/ 文件夹里；剧本按名字启动它，它会留在画面上，直到自己播完或对话框结束。

这是一个引擎模组，自己没有任何可见内容。目前收录的游戏还没有附带任何特效场景，所以游玩时不会遇到特效；这个模组是为想添加特效的作者准备的。

特效如何出现

1. 剧本中执行一行 effect <名字>。
2. Effects Engine 在已加载的模组中寻找 effects/<名字>.tscn 场景。
3. 特效被叠放在场景画面上——位于背景和其中的物体之上、对话框之下——并开始播放。
4. 启动它的对话框结束时，特效随之移除，除非它已经自行移除。

剧本不会等待特效：下一行立即显示。

给作者：添加特效

把特效场景放进你的模组：

my_mod/
└── effects/
    └── sparks.tscn

在剧本中启动它：

text "油灯闪烁了一下。"
effect sparks
text "黑暗中有什么东西动了一下。"
end

模组必须是文件夹。 Godot 场景只能从以文件夹形式安装的模组中加载。以 .zip 压缩包分发的模组，其特效会被跳过，并在日志中留下警告。

特效场景的积木

Effects Engine 提供三种在特效场景内部动画帧的方式：

• 带渐变的帧序列 — 一个挂有 EffectDataSet 脚本的节点、一组帧图片，以及一个在帧与帧之间做渐变的 AnimationController。速度和渐变时间在检查器中设置；帧只播放一遍，然后特效自行移除。
• 着色器里的雪碧图 — EffectAnimator 让带帧表材质的 TextureRect 在设定时长内步进设定的帧数。
• 不用着色器的雪碧图 — EffectAnimNode 沿水平雪碧图滚动（帧宽 = 图宽 / 帧数），播完自行移除。也可以用代码创建：EffectAnimNode.SpawnOn(target, sheet, frameCount, seconds)。

帧序列和无着色器雪碧图会拉伸铺满场景，因此按场景尺寸绘制的帧能与背景对齐。

不写代码的第一个特效

最简单的特效是一个根节点为 TextureRect 的场景，放一张拉伸到全屏的图片——比如一层半透明的光晕。它随 effect <名字> 出现，在对话框结束时消失。

出现问题时

1. 什么都没出现，日志说找不到特效。 文件必须位于加入游戏的某个模组的 effects/<名字>.tscn，且剧本中的名字要一致。
2. 特效在开发时正常，玩家却看不到。 模组是以 .zip 发布的；请以文件夹形式发布。
3. 特效迟迟不消失。 它会留到所在对话框结束；结束该对话框，或改用帧序列或雪碧图积木搭建特效——它们播完会自行移除。