架构概览¶
资源模型¶
SWF 动画通过 SwfResource 资源类型加载，挂载到 Swf 节点（继承 Node2D）上使用。
SwfResource 是 Godot 的标准资源类型，支持：
- 编辑器拖放 — 直接将 .swf 文件拖入节点属性
- 预加载 —
preload("res://my.swf") - 热重载 — 运行时替换 .swf 文件，模块自动安全切换到新内容
动画标识¶
SWF 文件中的动画通过两种方式定位：
| 方式 | 说明 | 运行时 API |
|---|---|---|
| 角色 ID | SWF 文件内部的数字索引 | play_id(id) |
| SymbolClass 名称 | SWF 文件中注册的字符串名称 | play_name(name) |
编辑器下可通过 animation_name 下拉枚举选择（选项来自 SWF 文件的 SymbolClass 标签），animation_id 作为备用。
播放控制¶
播放控制全部通过函数完成：
play_name()/play_id()— 启动播放stop()— 暂停，保持当前帧resume()— 从当前帧继续reset()— 彻底停止，回到第 0 帧goto_frame()— 跳转到指定帧索引goto_label()— 跳转到帧标签（FrameLabel）
goto_frame 和 goto_label 支持两个参数：
- stop — 跳转后停止在该帧
- play_children — stop 为 true 时，父节点停止但子 Sprite 继续播放
帧推进¶
模块按 SWF 文件头定义的 frame_rate 推进动画，子 Sprite 不独立累计时间，跟随父节点同步推进。
根实例变换¶
Swf 节点提供 root_position、root_rotation、root_scale、root_skew 属性，用于调整 SWF 内容内部根实例的变换。
SWF 内容的根实例在文件内部有自己的坐标位置。当根实例超出 render_target_size 定义的 cull rect 时，Godot 的屏幕遮挡剔除会将 Swf 节点误判为不可见。通过 root_position 等属性将内部根实例移到 cull rect 内，可确保遮挡剔除正常工作。
渲染设置¶
| 属性 | 说明 |
|---|---|
render_target_size |
渲染目标尺寸，加载 SWF 时自动匹配帧大小 |
loop |
是否循环播放 |
speed_scale |
播放速度倍率 |
编辑器功能¶
- 实时预览 — 编辑器下选中 Swf 节点即自动播放预览
- preview_frame — 冻结到指定帧，便于逐帧检查
- animation_name 下拉 — 枚举所有可用的动画名称
- auto_play — 设置后运行时自动播放（需配合 animation_name/animation_id）