文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载输出文章结束标记测试RectangleShape2D 是 Godot Engine 2D 物理系统中使用最广泛的碰撞形状之一它以矩形描述物体的碰撞边界通常挂载在CollisionShape2D节点下为Area2D、StaticBody2D、RigidBody2D或CharacterBody2D提供检测或实体碰撞能力。本指南将以 class_rectangleshape2d.rst 为骨架结合仓库内物理教程与相关类文档系统讲解其继承体系、核心size属性、性能定位、编辑器操作、代码创建方式以及可调用的基类方法帮助你准确选型并正确配置矩形碰撞体。RectangleShape2D 是什么类定义与继承体系依据官方类参考文档RectangleShape2D 的完整定义是A 2D rectangle shape used for physics collision.用于物理碰撞的 2D 矩形形状。它的继承链为RectangleShape2D Shape2D Resource RefCounted ObjectShape2D见 class_shape2d.rst是所有 2D 物理形状的抽象基类定义了一组通用的碰撞查询方法collide、collide_and_get_contacts等与属性custom_solver_biasResource意味着它是一个可复用、可保存、可在编辑器 Inspector 中直接编辑的资源类型RefCounted表示其生命周期由引用计数管理代码中创建后无需手动释放。文档明确指出其典型用途Usually used to provide a shape for a CollisionShape2D——即通过 CollisionShape2D 节点把形状挂到物理体上。官方在 physics_introduction.rst 中规定至少为一个物理对象分配一个 Shape2D 才能检测碰撞而最常见的方式就是把 CollisionShape2D 或 CollisionPolygon2D 作为物理体的直接子节点。注意间接子节点子节点的子节点会被忽略不会参与碰撞。核心属性 size 详解RectangleShape2D 只有一个专有属性类型属性默认值Vector2sizeVector2(20, 20)含义矩形的宽度与高度The rectangles width and height单位是像素。对应的 setter/getter 方法为set_size(value: Vector2)get_size() - Vector2默认值与使用建议默认Vector2(20, 20)是一个边长 20×20 像素的小矩形适合作为占位符。实际使用时通常需要根据精灵贴图尺寸调整。官方在 CharacterBody2D 教程 using_character_body_2d.rst 中的做法是为CharacterBody2D添加Sprite2D与CollisionShape2D在 Shape 属性中选择 New RectangleShape2D然后把矩形尺寸调整到刚好覆盖精灵图像。一个常见的坑是尺寸与缩放调整碰撞形状大小时应使用编辑器的尺寸手柄而不是Node2D的 Scale 手柄。官方在 physics_introduction.rst 中给出明确警告不要在编辑器中缩放碰撞形状Inspector 中的 Scale 应保持(1, 1)否则会产生意外的碰撞行为。Godot 4 迁移注意extents → size在 Godot 3 中该属性名为extents半宽高Godot 4 中改名为size完整宽高数值含义也由半边长变为全长。升级指南 upgrading_to_godot_4.rst 记录了这条变更RectangleShape2Dsextentsis nowsize因此从 Godot 3 迁移的代码原来set_extents(Vector2(50, 20))表示半宽 50、半高 20即整体 100×40迁移后应写作set_size(Vector2(100, 40))数值需加倍。这一点是实际项目中最容易踩的坑。性能定位与其他 2D 碰撞形状的对比官方类文档给出了明确的性能排序RectangleShape2D的碰撞检测速度较快。它比 CapsuleShape2D 快但比 CircleShape2D 慢。圆形碰撞见 class_circleshape2d.rst其中也交叉印证了该结论计算最廉价因为圆形只需比较圆心距离矩形只需比较 AABB 边界胶囊形则需要处理两端的圆弧开销更高。2D 形状整体性能参考来自 collision_shapes_2d.rst 与 class_shape2d.rst基础图元CircleShape2D、RectangleShape2D、CapsuleShape2D、SegmentShape2D、SeparationRayShape2D、WorldBoundaryShape2D速度快、行为可靠官方推荐动态物体RigidBody2D、CharacterBody2D优先使用基础图元ConvexPolygonShape2D凸多边形可表达任意凸形速度较慢ConcavePolygonShape2D凹多边形/三角网格最慢但最精确且只能用于 StaticBody2D不能用于 CharacterBody2D 或 RigidBody2D除非刚体模式为 Static。选型建议一个平台、墙、箱子、门等规则矩形物体用 RectangleShape2D 是精度与性能的最佳平衡若物体形状明显更接近圆形如硬币、轮子则应改用 CircleShape2D 换取更高性能角色等物体常由一个矩形加若干圆形组合表达。实战一在编辑器中创建矩形碰撞形状编辑器内创建流程以物理体 矩形碰撞为例在场景中创建物理体节点如StaticBody2D、CharacterBody2D或RigidBody2D右键该节点选择Add Child Node添加CollisionShape2D作为其直接子节点选中CollisionShape2D在 Inspector 的Shape属性下拉菜单中选择New RectangleShape2D使用 2D 视口顶部的尺寸手柄调整矩形大小使其贴合精灵或期望的碰撞范围见 physics_introduction.rst 中的示意图 player_coll_shape.webp展示了玩家碰撞形状覆盖在精灵上的典型配置。调试相关配置可参考 class_collisionshape2d.rstdebug_color编辑器中的显示颜色默认跟随ProjectSettings.debug/shapes/collision/shape_color在运行项目时可通过编辑器顶部的Debug Visible Collision Shapes开关查看所有碰撞形状的可视化轮廓便于验证矩形大小与位置是否正确。实战二通过代码创建与配置矩形碰撞形状GDScript 示例——动态为物理体挂载矩形碰撞extends StaticBody2D func _ready() - void: # 创建形状资源 var rect_shape : RectangleShape2D.new() rect_shape.size Vector2(64, 32) # 64 像素宽、32 像素高 # 创建碰撞形状节点并挂到物理体下 var col_shape : CollisionShape2D.new() col_shape.shape rect_shape add_child(col_shape)C# 等价实现using Godot; public partial class MyStaticBody2D : StaticBody2D { public override void _Ready() { var rectShape new RectangleShape2D(); rectShape.Size new Vector2(64, 32); var colShape new CollisionShape2D(); colShape.Shape rectShape; AddChild(colShape); } }要点RectangleShape2D作为 Resource 可以在多个节点间共享同一份形状资源可以被多个CollisionShape2D引用若需要运行时动态改变碰撞区域直接修改shape.size即可物理引擎会在下一步物理帧生效若希望临时禁用碰撞应通过CollisionShape2D.disabled实现官方文档建议使用set_deferred()修改该属性以规避物理引擎同步问题。继承自 Shape2D 的通用能力虽然 RectangleShape2D 自身只定义size但它完整继承了 Shape2D 的碰撞查询 API见 class_shape2d.rst这些方法接收本形状与其他形状各自的Transform2D非常适合做自定义碰撞检测、平台判定与移动预览方法说明collide(local_xform, with_shape, shape_xform) - bool判断两形状在当前位姿下是否碰撞collide_and_get_contacts(...) - PackedVector2Array返回接触点对成对交替排列本形状边界点、对方边界点用(B - A).normalized()求碰撞法线用(B - A).length()求穿透深度collide_with_motion(...) - bool判断若施加给定位移local_motion/shape_motion后是否会碰撞常用于移动预测collide_with_motion_and_get_contacts(...)预测位移后的接触点对get_rect() - Rect2返回形状的边界矩形对矩形形状而言即其自身范围draw(canvas_item, color)通过 RenderingServer 在 CanvasItem 上以指定颜色绘制实心形状典型用法在_physics_process()中调用collide_with_motion预先探测角色下一步是否会被矩形平台阻挡再决定移动或触发响应。另外Shape2D 的custom_solver_bias默认0.0可调整该形状参与接触分离时的求解偏向保持0时使用ProjectSettings.physics/2d/solver/default_contact_bias的全局默认值。一般场景无需修改。与 CollisionShape2D 及物理体的配合要点class_collisionshape2d.rst 中与矩形碰撞最相关的配置one_way_collision单向碰撞默认false启用后矩形只在指定方向的一侧检测碰撞常用于跳板式平台方向由one_way_collision_direction默认Vector2(0, 1)控制one_way_collision_margin默认1.0像素越大形状越厚对高速进入的碰撞体更友好。注意该特性在 Area2D 子节点上不生效disabled禁用后形状在世界中无任何效果。结合物理体类型来自 physics_introduction.rstArea2D矩形提供检测区域如触发器、危险区可发出 body_entered/exited 信号StaticBody2D矩形成为不可移动的实体地面、墙壁、箱子RigidBody2D矩形参与刚体动力学其尺寸还决定惯性矩官方注明需要激活的 CollisionShape2D 作为子节点才能正确计算惯性见 class_rigidbody2d.rstCharacterBody2D矩形作为角色的实体轮廓配合move_and_collide()/move_and_slide()实现移动与滑墙。性能注意事项与最佳实践综合官方文档 collision_shapes_2d.rst 的建议形状数量尽量少每个物理体的碰撞形状越少越好尤其对动态物体避免对碰撞形状做平移/旋转/缩放保持单一且未变换的形状可让引擎的 broad phase 算法直接淘汰不活跃的物理体缩小 narrow phase 的检测范围形状过多会导致 broad phase 失效碰撞检测整体变慢多形状间不必担心重叠同一物理体上的多个形状不会互相碰撞优先用图元表达小物体对于规则矩形物体一个 RectangleShape2D 通常就是最优解复杂大场景才考虑凸/凹多边形。相关资源类参考class_rectangleshape2d.rst、基类 class_shape2d.rst、挂载节点 class_collisionshape2d.rst教程2D 碰撞形状、物理入门、CharacterBody2D 使用教程迁移Godot 4 升级指南extents → size 变更示例官方 2D Pong Demo 与 2D Kinematic Character Demo 均使用了 RectangleShape2D可从 Godot 官方资源库获取赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot CircleShape2D 圆碰撞形状完全指南radius 参数、2D 物理性能与实战用法Godot CircleShape2D 圆碰撞形状完全指南radius 参数、2D 物理性能与实战用法 CircleShape2D 是 Godot 2D 物理文档教程游戏开发Godot 2D 碰撞形状节点 CollisionShape2D 完全指南属性详解、单向碰撞与性能调优Godot 2D 碰撞形状节点 CollisionShape2D 完全指南属性详解、单向碰撞与性能调优 本文围绕 Godot 官方文档仓库中的 Collisi文档教程游戏开发Godot 2D 物理碰撞完全指南CapsuleShape2D 胶囊碰撞体属性、约束与实战用法Godot 2D 物理碰撞完全指南CapsuleShape2D 胶囊碰撞体属性、约束与实战用法 导读 本文基于 Godot 官方文档godot docs中文档教程游戏开发上一篇11款游戏字体免费下载HoYo-Glyphs完整使用指南下一篇如何高效管理ComfyUI插件从零到精通的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考