Menu
用于 Godot 中 ParallaxBackground/ParallaxLayer 节点因视差乘数而在编辑器中 显示错误位置的情况。根据摄像机起始位置和视差运动缩放计算正确的编辑器位置。 使视差图层在编辑器中逼真预览，匹配游戏中的外观。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
当 Godot 代码中存在通过 get_node()、get_parent() 或直接引用产生的紧耦合依赖时使用。 检测耦合模式并将其转换为基于 Signal 的通信方式。组件变得独立、可测试且可复用。 在改进架构的同时精确保留原有行为。
当 Godot 代码中存在相互冲突的操作导致未定义行为时使用。检测同一属性在多处设置 （_ready、_process、代码+编辑器）、同一 Signal 多次连接、冲突的物理模式、 竞争的动画等问题。自动通过明确的所有权归属解决冲突。
用于创建带有自定义面板、停靠栏和工具的 Godot 编辑器插件。生成 plugin.cfg 配置、 EditorPlugin 脚本模板、自定义编辑器 UI 组件，并集成 ProjectSettings。按照 Godot 4.x 最佳实践创建完整的插件结构。
当 Godot 代码中存在硬编码的游戏数据（如 const 数组、字典或内嵌值）时使用。检测内联数据 如敌人属性、物品定义、关卡配置等。自动提取为 .tres Resource 文件，使数据在编辑器中 可见、易于修改，并支持数据驱动的设计。
当构建 Godot 功能时，代码使用 .new() 创建节点而非使用场景时触发。 检测 Timer.new()、Area2D.new()、Sprite2D.new() 等代码创建的对象。 自动生成 .tscn 场景文件，更新父脚本使用 @onready 引用，并创建可复用的组件库。
当 Godot 项目在编辑器（.tscn）和代码（.gd）之间存在位置冲突、相机跟随背景、 或运行时位置与编辑器预览不匹配时使用。编排所有 3 个位置同步子技能： sync-static-positions、sync-camera-positions 和 sync-parallax。 每个操作针对特定的位置冲突类型。
| name | godot-sync-parallax |
| version | 3.0.0 |
| displayName | 同步视差图层位置 |
| description | 用于 Godot 中 ParallaxBackground/ParallaxLayer 节点因视差乘数而在编辑器中 显示错误位置的情况。根据摄像机起始位置和视差运动缩放计算正确的编辑器位置。 使视差图层在编辑器中逼真预览，匹配游戏中的外观。 |
| author | Asreonn |
| license | MIT |
| category | game-development |
| type | tool |
| difficulty | intermediate |
| audience | ["developers"] |
| keywords | ["godot","parallax","parallax-background","parallax-layer","motion-scale","editor-preview","camera-position","gdscript"] |
| platforms | ["macos","linux","windows"] |
| repository | https://github.com/asreonn/godot-superpowers |
| homepage | https://github.com/asreonn/godot-superpowers#readme |
| permissions | {"filesystem":{"read":[".gd",".tscn"],"write":[".tscn"]},"git":true} |
| behavior | {"auto_rollback":true,"validation":true,"git_commits":true} |
| outputs | 同步后的视差位置、校正后的图层偏移、更新的 .tscn 文件、git 提交 |
| requirements | Git 仓库、Godot 4.x |
| execution | 根据视差属性自动计算 |
| integration | 属于 godot-fix-positions 编排器的一部分，专用于视差系统 |
视差图层需要特殊的数学计算才能在编辑器中正确预览。 Motion scale 会影响运行时位置。
Godot 中的视差系统比较复杂：
# Godot 的视差公式：
final_position = layer_position - (camera_position * motion_scale)
问题：
layer_positionlayer_position - (camera_position * motion_scale)解决方案：
计算正确的 layer_position，使运行时外观匹配预期设计。
# parallax_background.tscn
[node name="ParallaxBackground" type="ParallaxBackground"]
[node name="SkyLayer" type="ParallaxLayer" parent="."]
motion_scale = Vector2(0.2, 0.2) # 慢速视差
position = Vector2(0, 0)
# 摄像机起始于 (640, 360)
# 运行时位置：0 - (640 * 0.2) = -128（错误！）
# 天空图层在游戏中向左偏移
同步后：
[node name="SkyLayer" type="ParallaxLayer" parent="."]
motion_scale = Vector2(0.2, 0.2)
position = Vector2(128, 72) # 已校正！
# 运行时位置：128 - (640 * 0.2) = 0（正确！）
# 天空图层在游戏中居中显示，与编辑器一致
识别视差系统：
[node name="ParallaxBackground" type="ParallaxBackground"]
scroll_offset = Vector2(0, 0)
scroll_base_scale = Vector2(1, 1)
[node name="Layer1" type="ParallaxLayer" parent="."]
motion_scale = Vector2(0.5, 0.5)
motion_offset = Vector2(0, 0)
[node name="SkyLayer" parent="ParallaxBackground"]
motion_scale = Vector2(0.1, 0.1) # 非常慢（远处）
[node name="MountainsLayer" parent="ParallaxBackground"]
motion_scale = Vector2(0.3, 0.3) # 较慢（中距离）
[node name="TreesLayer" parent="ParallaxBackground"]
motion_scale = Vector2(0.7, 0.7) # 较快（近处）
在编辑器中创建多层视差效果。
图层在游戏中出现在错误位置。
希望视差系统实现所见即所得。
具有不同缩放比例的复杂多层视差。
displayed_position = layer_position - (camera_position * motion_scale)
layer_position = desired_position + (camera_position * motion_scale)
希望天空图层在游戏中居中于 (0, 0)：
之前（错误）：
[node name="SkyLayer" type="ParallaxLayer"]
motion_scale = Vector2(0.2, 0.2)
position = Vector2(0, 0)
# 精灵在图层相对位置 (0, 0)
# 摄像机在 (640, 360)
# 运行时：0 - (640 * 0.2) = -128
# 天空向左偏移了 -128 像素（错误）
之后（修正）：
[node name="SkyLayer" type="ParallaxLayer"]
motion_scale = Vector2(0.2, 0.2)
position = Vector2(128, 72) # 已校正
# 精灵在图层相对位置 (0, 0)
# 运行时：128 - (640 * 0.2) = 0
# 天空居中显示（正确）
之前（全部在原点）：
[node name="Sky" type="ParallaxLayer"]
motion_scale = Vector2(0.1, 0.1)
position = Vector2(0, 0)
[node name="Mountains" type="ParallaxLayer"]
motion_scale = Vector2(0.3, 0.3)
position = Vector2(0, 0)
[node name="Trees" type="ParallaxLayer"]
motion_scale = Vector2(0.7, 0.7)
position = Vector2(0, 0)
# 所有图层在运行时向左偏移
之后（已校正）：
[node name="Sky" type="ParallaxLayer"]
motion_scale = Vector2(0.1, 0.1)
position = Vector2(64, 36) # 640*0.1, 360*0.1
[node name="Mountains" type="ParallaxLayer"]
motion_scale = Vector2(0.3, 0.3)
position = Vector2(192, 108) # 640*0.3, 360*0.3
[node name="Trees" type="ParallaxLayer"]
motion_scale = Vector2(0.7, 0.7)
position = Vector2(448, 252) # 640*0.7, 360*0.7
# 所有图层在运行时正确居中
组合公式：
displayed_position = (layer_position + motion_offset) - (camera_position * motion_scale)
同步时会同时考虑这两个属性。
识别视差系统：
检测摄像机：
计算校正：
可搭配使用：
以下情况不要同步：
[node name="CloudsLayer" type="ParallaxLayer"]
motion_scale = Vector2(0.2, 0) # 仅水平
motion_mirroring = Vector2(1280, 0) # 水平重复
同步：仅校正水平位置。
[node name="SkyLayer" type="ParallaxLayer"]
motion_scale = Vector2(0, 0.1) # 仅垂直
同步：仅校正垂直位置。
[node name="BackgroundLayer" type="ParallaxLayer"]
motion_scale = Vector2(0.3, 0.3) # 双轴
同步：同时校正 x 和 y 位置。
同步后验证：
# 视差图层已根据摄像机起始位置校正：(640, 360)
# motion_scale: (0.2, 0.2)
# 公式：position = desired_runtime_position + (camera * motion_scale)
# 计算：(0, 0) + (640 * 0.2, 360 * 0.2) = (128, 72)
清晰的文档展示计算方法。
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 图层在游戏中向左偏移 | position = (0,0)，motion_scale < 1 | 添加偏移：camera * motion_scale |
| 图层在开始时跳动 | 编辑器位置不等于运行时位置 | 使用公式同步位置 |
| 图层对不齐 | 不同的摄像机假设 | 统一摄像机起始位置 |
| 预览与游戏不匹配 | 未考虑视差数学 | 应用反向视差公式 |
视差系统效率很高，但需注意：
同步位置不影响性能，只影响编辑器可用性。