godot-genre-platformer

绝不该做的事（专家级反模式）

物理与移动手感

• 绝不要在调用 move_and_slide() 前将速度乘以 delta；该方法会在内部处理时间步长。
• 绝不要省略土狼时间（约 0.1s）；没有这段宽限时间，玩家走下悬崖时跳跃会显得反应迟钝。
• 绝不要忽略跳跃缓冲（约 0.15s）；玩家提前按下跳跃键后，会期待角色一触地就立刻起跳。
• 绝不要使用固定跳跃高度；务必实现可变跳跃高度（松开按键时截断速度），让玩家能够自主掌控。
• 绝不要忘记在将重力加到速度前乘以 delta；重力是加速度，必须与帧率无关。
• 绝不要依赖离散碰撞来处理高速移动；务必使用 CCD_MODE_CAST_RAY，避免穿透几何体。
• 绝不要在标准移动中使用 move_and_collide()；它缺少 move_and_slide() 的斜坡和台阶处理能力。
• 绝不要用精确相等（== 0.0）检查土狼时间或缓冲计时器；务必使用 is_equal_approx() 或 >= 0.0。

润色与关卡设计

• 绝不要使用线性摄像机吸附；务必使用摄像机平滑或 lerp()，以避免晕动症。
• 绝不要省略跳跃/落地时的挤压与拉伸；缺少这些细微的视觉“活力”提示，移动会显得毫无重量。
• 绝不要设计盲跳；务必使用摄像机前瞻或缩放触发器显示着陆区域。
• 绝不要使用单独的 Sprite2D 节点构建关卡几何体；务必使用 TileMapLayer，以优化碰撞和渲染。
• 绝不要为玩家使用复杂/凹形的 CollisionShape2D；务必优先使用基本形状（胶囊体/矩形），以确保稳定性。

架构与性能

• 绝不要用 CharacterBody2D 实现简单的移动平台；务必使用 AnimatableBody2D 并启用 sync_to_physics。
• 绝不要忽略下降平台的 platform_on_leave；使用 PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY 保留跳跃冲量。
• 绝不要对玩家角色禁用 recovery_as_collision；正确报告地面吸附状态必须启用此项。
• 绝不要在 AnimationTree 表达式中使用 !（NOT）运算符；务必使用 is_walking == false。
• 绝不要在高频状态检查中使用标准 String；务必使用 StringName（例如 &"jumping"）。
• 绝不要同步加载大型关卡区块；务必使用 ResourceLoader.load_threaded_request()，避免帧卡顿。

---

可用脚本

必需：要调整移动手感，请阅读控制器和模块——不要内联重写土狼时间/缓冲/可变跳跃逻辑。

控制器（推荐方案）

• advanced_platformer_controller.gd — 必读，适用于任何需要精准跳跃/奔跑的控制器。
• platformer_controller_2d.gd — 当高级方案过于复杂时，可作为更精简的 CharacterBody2D 基础实现。
• player_ground_controller.gd — 地面恒速与斜坡吸附优化。

移动模块

• coyote_timer.gd — 必需，用于跳跃手感优化（或使用集成了该功能的高级控制器）。
• jump_buffer.gd — 必需，需与土狼时间搭配使用，以提升落地响应。
• variable_jump.gd — 必需，用于通过松开按键截断跳跃高度。
• wall_slide_sensor.gd — 无节点墙壁检测。
• ledge_grab_sensor.gd — 基于形状查询的边缘抓取。
• one_way_drop_handler.gd — 必读，适用于穿落平台/单向平台输入处理。
• custom_collision_slider.gd — 高速移动时的帧间滑动响应。

世界 / 摄像机 / 润色

• synchronized_platform.gd — 使用 sync_to_physics 的 AnimatableBody2D 平台。
• fast_projectile_ccd.gd — 使用 CCD 防止穿透。
• platformer_animation_sync.gd — 布尔值安全的 AnimationTree 同步。
• platformer_camera.gd — 前瞻 / 平滑处理（搭配 godot-camera-systems）。
• game_feel_helper.gd — 在视觉节点上通过 Tween 实现挤压 / 拉伸（以脚部为轴心）。
• speed_trail.gd — 切换 GPUParticles 拖尾，为冲刺 / 奔跑增添动感。
• checkpoint.gd — Area2D 检查点 ID + SaveManager 位置钩子。

---

核心循环

跳跃 → 绕过障碍 → 抵达目标 → 进入下一关

技能链

godot-project-foundations、godot-characterbody-2d、godot-input-handling、godot-2d-animation、godot-audio-systems、godot-tilemap-mastery、godot-camera-systems、godot-monte-carlo-balancer

---

移动手感 — 决策参数（非教程）

必须阅读：advanced_platformer_controller.gd 以及 coyote_timer.gd / jump_buffer.gd / variable_jump.gd。复制这些模块；不要在此处粘贴土狼时间 / 跳跃缓冲的实现方案。

阅读脚本后，只调整项目代码中的以下参数：

参数	专家默认值 / 说明
土狼时间窗口	~0.1s — 没有它，平台边缘跳跃会让人觉得失灵
跳跃缓冲	~0.15s — 提前按下的跳跃键必须在落地时生效
可变跳跃	松开按键时削减向上的速度
跳跃顶点 / 下落重力	顶点后提高下落重力倍率 = 更干脆地落地
CCD	为高速投射物 / 冲刺启用射线投射 CCD
移动平台	AnimatableBody2D + sync_to_physics；设置 platform_on_leave
单向平台	one_way_drop_handler.gd — 使用遮罩 / 层，而非临时禁用

地面：方向响应即时。空中：加速度略低。重力按 delta 缩放；调用 move_and_slide() 前绝不要执行 velocity *= delta。

---

关卡设计原则

“教学三部曲”

1. 引入 — 安全学习 → 2. 挑战 — 中等风险 → 3. 变化 — 组合机制 / 时间压力

流程与节奏

简单 → 简单 → 中等 → 检查点 → 中等 → 困难 → 检查点 → Boss

摄像机

使用 platformer_camera.gd / 同类项目 godot-camera-systems 实现前瞻——绝不要让玩家盲跳。

---

平台游戏子类型

• 精准跳跃（Celeste / Super Meat Boy）— 立即重生、操作精准、检查点频繁
• 收集类 — 枢纽世界、能力解锁、折返探索
• 解谜类 — 节奏缓慢、环境物理
• 银河恶魔城 — 路线参见 godot-genre-metroidvania

---

常见问题

问题	解决方案
跳跃飘忽	提高顶点后的下落重力
落点不准	土狼时间 + 跳跃缓冲模块 + 落地动效
死亡不公平	在接触前明确提示危险
盲跳	前瞻摄像机 / 缩放触发器
中期无聊	每 2–3 关引入新机制

---

润色清单

• 落地 / 奔跑时添加尘土粒子
• 重重落地时添加屏幕震动（godot-camera-systems 的 trauma）
• 跳跃 / 落地时添加挤压 / 拉伸（视觉轴心位于脚部）
• 添加跳跃 / 落地 / 蹬墙滑行音效
• 添加检查点视觉 / 音效反馈
• 添加辅助模式 / 可重新映射的控制

必须阅读，深入了解决策树和脚本目录之外的内容：platformer-movement-deep.md。首次接线时不要加载——先使用随附的 scripts/。

Godot 专属技巧

1. CharacterBody2D 与 RigidBody2D：平台跳跃游戏角色始终使用 CharacterBody2D——精准控制至关重要
2. 物理帧率：可考虑使用 120Hz 物理帧率，让移动更流畅
3. 单向平台：使用 set_collision_mask_value() 或专用碰撞层
4. 墙面检测：使用 is_on_wall() 和 get_wall_normal() 实现蹬墙跳

---

可供参考的游戏

• Celeste - 出色的游戏手感、无障碍辅助模式
• Hollow Knight - 战斗与平台跳跃的融合
• Super Mario Bros. Wonder - 精致的视觉效果与惊喜
• Shovel Knight - 复古机制与现代手感

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；在切换到相关领域时加载相关技能——不要预先加载整个技能网络。

官方文档

• 使用 CharacterBody2D — move_and_slide 提供的地面／墙面／天花板状态报告、斜坡吸附，以及影响平台跳跃手感的离开平台行为。
• CharacterBody2D — 用于精准控制器的 floor_constant_speed、floor_snap_length、recovery_as_collision 和运动模式参数。
• 物理简介 — 为玩家、单向平台、危险物和投射物设置碰撞层／遮罩，避免意外重叠。
• 碰撞形状（2D） — 解释胶囊形／矩形玩家形状为何比凹面几何体更稳定。
• 2D 移动概览 — CharacterBody 与 RigidBody 的权衡，以及常见的输入→速度模式。
• 使用 TileMaps — 使用 TileMapLayer 碰撞来构建关卡几何，而非为每个精灵单独设置 StaticBody。
• 使用 TileSets — 在图块集中配置单向碰撞和物理层，实现可穿透下落的平台。
• AnimatableBody2D — 使用 sync_to_physics 的移动平台，让平台上的角色保持贴合且不发生抖动。
• Camera2D — 位置平滑、拖动边距和前瞻偏移，避免盲目跳跃和晕动症。
• 使用 AnimationTree — 为待机／奔跑／空中状态设置布尔值推进条件，避免使用不安全的表达式取反。
• 射线投射 — 通过 PhysicsDirectSpaceState2D 查询墙面滑行和平台边缘，无需节点。
• 输入示例 — 跳跃缓冲和可变跳跃高度截断所用的动作刚按下／刚释放模式。

相关技能

前置条件

• godot-project-foundations — 在设置土狼时间／输入缓冲计时器前，先配置项目设置、输入映射动作和场景结构。
• godot-characterbody-2d — move_and_slide 的落地检测、斜坡和墙面法线，是所有精准跳跃的基础。
• godot-input-handling — 可重新映射的跳跃／移动动作，以及用于无障碍辅助模式的未处理输入缓冲。

补充内容

• godot-2d-physics — 控制器核心之外的图层、CCD、Area2D 危险区域和 AnimatableBody 平台。
• godot-tilemap-mastery — 用于构建可教学关卡几何结构的 TileMapLayer/TileSet 单向平台和碰撞绘制。
• godot-camera-systems — 前瞻、房间摄像机和平滑处理，让玩家看清落点，避免盲目跳跃。
• godot-animation-tree-mastery — 根据 is_on_floor / velocity 同步 AnimationTree 条件，构建不会影响操作手感的状态图。
• godot-2d-animation — 物理运算完成后，通过挤压/拉伸和落地/跑步循环展现重量感。
• godot-particles — 在跳跃/落地事件中触发尘土尾迹和落地烟尘。
• godot-audio-systems — 跳跃/落地/蹬墙滑行音效的时机设计，增强响应灵敏的手感。
• godot-monte-carlo-balancer — 在发布辅助默认设置之前，采样土狼时间/输入缓冲/重力/跳跃参数和关卡难度曲线。

下游 / 使用方

• godot-genre-metroidvania — 由能力门控的探索玩法，复用精确移动机制和 TileMap 房间。
• godot-save-load-systems — 在死亡和场景重新加载后持久保存检查点位置。

主模块

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。