godot-characterbody-2d

CharacterBody2D 实现

专家级 CharacterBody2D 操控手感系统——不是面向初学者的 move_and_slide 教程。

切勿这样做

• 切勿将 RigidBody2D 用于标准玩家控制器——RigidBody 用于受物理模拟的对象。要实现响应灵敏、注重手感的玩家移动，始终使用 CharacterBody2D。
• 切勿在调用 move_and_slide() 前将 velocity 乘以 delta——move_and_slide() 会在内部处理 delta。手动相乘会导致移动受帧率影响。
• 切勿使用 global_position 更新游戏移动——使用 velocity + move_and_slide()。直接修改位置会绕过碰撞、地面吸附和单向碰撞规则。
• 切勿通过微调 position.y 来“穿过”单向平台——应使用单向碰撞形状 + 图层/掩码（以及临时禁用掩码 / 与区域碰撞模式）。参见 godot-2d-physics。
• 切勿忽略调用 move_and_slide() 后的地面/墙面/天花板状态——is_on_floor()、is_on_wall()、is_on_ceiling() 和滑动碰撞信息是土狼时间、蹬墙跳和撞头逻辑的依据。
• 切勿依赖默认的 floor_snap_length 快速爬楼梯——默认吸附距离对于高速移动的角色来说太短。使用基于自定义射线检测的楼梯逻辑。
• is_on_floor() 为 true 时切勿施加重力——持续向下的力会导致微抖动，并与地面吸附冲突。落地时重置 velocity.y。
• 切勿将 Area2D 用作主要的地面检测方式——优先使用 is_on_floor() / 形状投射；Area 用于触发，不用于判定是否着地。
• 切勿忘记处理撞头——当 is_on_ceiling() 为 true 时重置 velocity.y，否则玩家会一直浮在天花板上，直到重力占上风。
• 切勿为像素画对物理位置取整——保持物理运算的高精度；仅在 _process 中对 精灵 位置取整（subpixel_movement_rounding.gd）。
• 切勿对大量对象频繁调用 queue_free()——如果生成/销毁频率很高，应复用子弹/敌人对象（performance_character_pooling.gd）。

---

何时使用 CharacterBody2D

需求	刚体
注重手感的玩家 / NPC / 敌人移动	CharacterBody2D
滚动的碎片、布娃娃状道具、受力堆叠物	RigidBody2D
静态关卡碰撞体	StaticBody2D / TileMapLayer physics

决策树 → 必须使用的脚本

任务	首先执行	然后（可选）	不要加载
平台跳跃游戏基础（宽限时间、输入缓冲、加速度／摩擦力）	expert_physics_2d.gd	—	内联教程控制器
仅隔离宽限时间／输入缓冲	frame_perfect_coyote_time.gd	—	SKILL 中重复的宽限时间代码块
可变跳跃高度／短跳	variable_jump_height.gd	—	—
斜坡／楼梯	slope_stair_snapping.gd	godot-raycasting-queries	—
蹬墙滑行／蹬墙跳	wall_slide_jump_refined.gd 或 wall_jump_controller.gd	—	除非进行比较，否则不要同时加载两者
冲刺 + 无敌帧	dash_state_controller.gd 或 dash_controller.gd	—	除非进行比较，否则不要同时加载两者
空中操控打磨	aerial_drift_acceleration.gd	—	—
头顶碰撞／撞顶	ceiling_bonk_detection.gd	—	—
击退／风力冲量	impulse_response_handler.gd	—	—
像素艺术视觉效果	subpixel_movement_rounding.gd	—	在物理过程中对 global_position 进行舍入
大量 AI 身体	performance_character_pooling.gd	—	—
单向平台	Tile/StaticBody 单向设置 + 图层／遮罩	godot-tilemap-mastery / godot-2d-physics	position.y += 1 穿平台的变通写法
俯视角／坦克式移动	movement-recipes.md	—	内联的八向移动教程
跳跃轨迹调试与调整	game_feel_profiler.gd	—	—
动画根运动	root_motion_controller.gd	godot-2d-animation	—

推荐路径： 首先阅读 expert_physics_2d.gd。只有在该控制器就位后，才添加冲刺／蹬墙／跳跃脚本。如果脚本已经负责处理宽限时间／输入缓冲／加速度循环，就不要在场景中再次内联实现。

单向平台（正确方案）

1. 在平台碰撞体上设置单向属性（CollisionShape2D 单向设置／TileSet 物理单向设置），不要通过传送玩家来实现。
2. 为平台和玩家设置明确的碰撞图层／遮罩，这样按住下方向键 + 跳跃时，就能临时清除平台位标志（或禁用碰撞）；然后在接下来的物理帧中恢复。
3. 在物理帧中处理穿平台；绝不要通过 position 微调绕过 move_and_slide。
4. 对于图块单向平台，应将 TileSet 物理图层与 CharacterBody 遮罩对齐 — 参见 godot-tilemap-mastery + godot-2d-physics。

专家级角色架构

1. 蹬墙停留（可变摩擦力）

下落时监测 is_on_wall()；通过摩擦因子缩放 velocity.y（可选地从图块自定义数据中获取），而不是使用二元的蹬墙滑行布尔值。优先使用 wall_slide_jump_refined.gd，而不是自行定制的蹬墙停留分支。

2. 动画驱动移动（根运动）

获取 AnimationTree.get_root_motion_position()，转换为 2D，赋值给 velocity = motion / delta，然后调用 move_and_slide()。这样可以让双脚与制作好的动画片段保持贴合；可搭配 godot-2d-animation。

3. 游戏手感分析器（跳跃弧线）

在 _draw() 中调试绘制历史位置和当前速度，以便在调节 expert_physics_2d.gd 中的导出变量时，观察顶点、土狼时间和输入缓冲窗口 — game_feel_profiler.gd。

对于俯视角／坦克式方案、移动平台、滑动碰撞响应和易错点表格，必须参阅：movement-recipes.md。如果 expert_physics_2d.gd 已涵盖你的平台游戏需求，则不要加载。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接； 在将工作分流至相关领域时加载关联技能 — 不要预先加载整个技能集。

官方文档

• 使用 CharacterBody2D — move_and_slide 以及地面／墙面／天花板判定的权威说明；游戏过程中的移动不要设置 position。
• CharacterBody2D — 关于 velocity、吸附、is_on_floor／墙面／天花板判定以及滑动碰撞访问器的 API。
• 物理简介 — CharacterBody 与 RigidBody／StaticBody 的区别，以及图层／遮罩如何控制每次接触。
• 碰撞形状（2D） — 胶囊／方框的尺寸设置，以及缩放 CollisionShape2D 节点为何会破坏法线和地面检测。
• 2D 移动 — 在添加增强手感的系统前，将输入轴转换为速度，适用于俯视角和平台游戏入门项目。
• 运动学角色（2D） — 经典的滑动／碰撞循环模式，仍可用于自定义楼梯和斜坡处理。
• 物理问题排查 — 单向平台、穿透和抖动问题的诊断方法，这些问题常会影响 CharacterBody 的手感。
• 射线投射 — 用于楼梯吸附、边缘检测和地面探测的直接空间射线，适用于 is_on_floor() 之外的场景。
• KinematicCollision2D — 通过 get_slide_collision 获取每次滑动的法线／剩余位移，用于墙跳和撞到天花板时的反应。
• 物理插值简介 — 在保持跳跃／土狼时间逻辑按物理帧运行的同时，于高刷新率下平滑视觉效果。
• InputEvent — 跳跃缓冲和土狼时间窗口所依赖的动作刚按下时序。

关联技能

前置条件

• godot-project-foundations — 必须先设置默认重力、物理帧率和 2D 图层名称，之后才能调校土狼时间和跳跃手感。
• godot-gdscript-mastery — 类型化的 _physics_process、计时器和 move_toward 规范，是此处所有移动脚本的基础。
• godot-2d-physics — CharacterBody 的运动依赖碰撞层/遮罩矩阵、单向形状和查询规范。
• godot-input-handling — 在物理帧采样操作，确保跳跃缓冲和土狼时间窗口的帧间表现稳定。

补充

• godot-raycasting-queries — 楼梯吸附、贴墙探测和超出 is_on_* 辅助函数范围的平台边缘射线。
• godot-tilemap-mastery — 单向瓦片和瓦片物理层必须与平台的 CharacterBody 遮罩匹配。
• godot-2d-animation — 根据地面/空中/冲刺状态驱动行走、跳跃和下落动画片段，同时避免与 move_and_slide 冲突。
• godot-state-machine-advanced — 相比庞大的 _physics_process 分支，冲刺、贴墙滑行和空中状态更易扩展。
• godot-camera-systems — 跟随/前瞻摄像机与 CharacterBody 速度和着陆吸附紧密相关。
• godot-signal-architecture — 着陆、冲刺和蹬墙跳事件需要明确的归属，避免 UI/VFX 监听器重复触发。

下游 / 使用方

• godot-genre-platformer — 平台游戏的整体手感会用到此技能中的土狼时间、跳跃缓冲、斜坡和单向平台。
• godot-genre-metroidvania — 受能力限制的移动（蹬墙跳、冲刺）基于此处定义的控制器构建。
• godot-combat-system — 击退和受击硬直通过同一套 velocity + 滑动循环施加冲量。
• godot-monte-carlo-balancer — 土狼帧数、跳跃高度、冲刺冷却时间和空中加速度都是平衡参数，应通过模拟验证，而不是凭猜测。

主入口

• godot-master — 库路由器，也是 CharacterBody2D 在相关领域中的镜像入口。