文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载本文围绕 Godot 引擎 2D 物理体系中的PhysicsIntersectShapeResult2D结果类展开讲解它如何承接PhysicsDirectSpaceState2D.intersect_shape_into()产生的形状相交数据并通过max_intersections与五个取值方法完成多命中对象的读取。读完本文你将掌握形状区域查询 结果对象复用这一零分配、可限制命中数量的物理查询模式并能在 GDScript 与 C# 中独立写出完整的形状探测代码。类概览形状相交查询的结果容器PhysicsIntersectShapeResult2D是 Godot 2D 物理查询体系中专门用于承载形状与空间中其他形状相交结果的对象。它的官方定位是Stores the results of a shape intersection query即存储一次形状相交查询的结果其类参考文档位于 classes/class_physicsintersectshaperesult2d.rst。它的继承关系为PhysicsIntersectShapeResult2D RefCounted Object继承自RefCounted意味着该对象由引用计数管理当不再有任何引用指向它时会被自动释放因此不需要手动free()。它的直接上游是 PhysicsDirectSpaceState2D该结果对象本身不能独立产生数据而是由PhysicsDirectSpaceState2D.intersect_shape_into()在查询成功后把相交信息写入其中。这一查询方法 结果对象的配对模式在 Godot 4 中是一套贯穿 2D/3D 物理查询的统一设计。该结果对象可以同时存放多个相交命中multiple intersections具体容量由用户通过max_intersections属性控制默认上限为 32。核心属性max_intersections 控制命中容量PhysicsIntersectShapeResult2D只有一个属性属性类型默认值说明max_intersectionsint32该结果对象最多可以存储的相交数量上限属性描述原文为The maximum number of intersections this result object can store。它通过set_max_intersections(value)与get_max_intersections()两个访问器读写。从 PhysicsDirectSpaceState2D.intersect_shape_into() 的方法说明可以确认其用途查询命中后相交数据被写入结果对象而相交数量可以通过max_intersections来限制以减少处理时间The number of intersections can be limited usingmax_intersections, to reduce the processing time。实践要点默认 32 足够覆盖绝大多数场景如技能范围探测、AI 感知圈通常无需修改当查询区域可能同时命中大量对象、而你只关心前几个结果时把max_intersections调小可以显著减少物理引擎的整理与存储开销由于该对象通常复用见下文复用结果对象建议在初始化阶段就设置好容量避免在热循环中反复调整。五个取值方法逐条读取命中信息结果对象通过以下 5 个方法按索引intersection_index访问每一次命中。索引从 0 开始有效范围是0到get_intersection_count() - 1。方法签名返回类型含义get_collider(intersection_index)Object发生碰撞的对象碰撞体节点实例get_collider_id(intersection_index)int碰撞对象的 ObjectIDget_collider_rid(intersection_index)RID相交对象的 RID服务器层标识get_collider_shape(intersection_index)int被碰撞形状在其所属对象上的形状索引shape indexget_intersection_count()int与查询形状相交的形状总数其中get_intersection_count()是整个结果对象的总数入口其余四个方法都需要传入intersection_index定位到具体某一次命中。四个取值方法返回的信息维度各不相同在实际开发中通常组合使用get_collider()返回的是场景节点层对象适合直接做类型判断is Area2D、is CharacterBody2D等、访问其脚本或属性、调用其方法get_collider_id()返回对象的唯一 ID适合做去重、缓存或跨帧追踪即使对象后来被释放也能通过 ID 判断是否见过get_collider_rid()返回物理服务器层面的 RID是对象在PhysicsServer2D中的身份标识适合与服务器 API 交互或在exclude列表中使用get_collider_shape()返回碰撞形状索引当同一对象挂着多个CollisionShape2D时用它区分到底是哪个子形状被命中。与intersect_shape()返回字典数组不同这四个方法都是const方法文档中以const标注表示不修改实例状态、无副作用因此可以在任意时间重复读取无需担心查询结果被破坏。完整实战从查询参数到结果遍历第一步获取 2D 空间状态PhysicsIntersectShapeResult2D依赖PhysicsDirectSpaceState2D产生数据。后者不能直接实例化需要通过World2D.direct_space_state获取见 PhysicsDirectSpaceState2D 文档说明。官方 ray-casting 教程 强调物理空间只在_physics_process()回调期间可以安全访问在其它时机访问可能因空间被锁定而报错。extends Node2D func _physics_process(_delta): var space_state : get_world_2d().direct_space_state # 在 _physics_process 内执行查询…using Godot; public partial class MyNode2D : Node2D { public override void _PhysicsProcess(double delta) { var spaceState GetWorld2D().DirectSpaceState; // 在 _PhysicsProcess 内执行查询… } }第二步构建查询参数 PhysicsShapeQueryParameters2Dintersect_shape_into()的第一参数是 PhysicsShapeQueryParameters2D它集中描述了查询形状、位置姿态与过滤规则var params : PhysicsShapeQueryParameters2D.new() params.shape preload(res://query_shape.tres) # 查询用的 Shape2D 资源 params.transform Transform2D(0, global_position) # 形状在全局坐标系中的位置 params.collision_mask 0b0001 # 只查询第 1 层 params.collide_with_areas true # 是否把 Area2D 计入结果默认 false params.collide_with_bodies true # 是否把 PhysicsBody2D 计入结果默认 true params.exclude [self] # 排除自身避免自命中各过滤属性默认值如下均可在 PhysicsShapeQueryParameters2D 文档中核实collide_with_areas false、collide_with_bodies true、collision_mask 4294967295即检测所有碰撞层、exclude []、margin 0.0、motion Vector2(0, 0)、transform为单位矩阵。注意exclude数组的语义它存放的是对象 RID 列表可以用CollisionObject2D.get_rid()获取某个 2D 碰撞对象的 RID见 CollisionObject2D 文档。官方文档还特别提示该数组返回的是副本修改后需要重新赋值回属性才生效。第三步复用结果对象并执行查询intersect_shape_into()的签名是bool intersect_shape_into(parameters: PhysicsShapeQueryParameters2D, result: PhysicsIntersectShapeResult2D)。与返回新分配的字典数组的intersect_shape()不同它把数据写入调用方传入的预分配结果对象从而避免每帧分配新数组——这是into 系列方法intersect_point_into、intersect_ray_into、collide_shape_into、get_rest_info_into、cast_motion_into的共同设计。var result : PhysicsIntersectShapeResult2D.new() result.max_intersections 8 # 本帧最多取前 8 个命中降低处理开销 func _physics_process(_delta): var space_state : get_world_2d().direct_space_state var params : PhysicsShapeQueryParameters2D.new() params.shape my_shape params.transform Transform2D(0, global_position) params.collide_with_bodies true if space_state.intersect_shape_into(params, result): for i in result.get_intersection_count(): var collider : result.get_collider(i) var collider_id : result.get_collider_id(i) var rid : result.get_collider_rid(i) var shape_idx : result.get_collider_shape(i) print(命中对象: , collider, ID: , collider_id, RID: , rid, 形状索引: , shape_idx) else: print(本次查询没有任何形状相交)using Godot; public partial class MyNode2D : Node2D { private PhysicsIntersectShapeResult2D _result new() { MaxIntersections 8 }; public override void _PhysicsProcess(double delta) { var spaceState GetWorld2D().DirectSpaceState; var parameters new PhysicsShapeQueryParameters2D { Shape MyShape, Transform new Transform2D(0, GlobalPosition), CollideWithBodies true }; if (spaceState.IntersectShapeInto(parameters, _result)) { for (int i 0; i _result.GetIntersectionCount(); i) { var collider _result.GetCollider(i); var colliderId _result.GetColliderId(i); var rid _result.GetColliderRid(i); var shapeIdx _result.GetColliderShape(i); GD.Print($命中对象: {collider}, ID: {colliderId}, RID: {rid}, 形状索引: {shapeIdx}); } } else { GD.Print(本次查询没有任何形状相交); } } }第四步验证查询是否成功intersect_shape_into()的返回值本身就是查询结果标志若发现一个或多个形状与查询形状相交返回true并把数据写入结果对象若没有任何相交返回false。因此最稳妥的读取习惯是先判断返回值再遍历get_intersection_count()。如果直接忽略返回值在零命中的情况下遍历次数为 0虽然不会崩溃但容易掩盖查询到底有没有执行的问题。与 intersect_shape() 字典版本的对比PhysicsDirectSpaceState2D同时提供intersect_shape()与intersect_shape_into()两个形状查询入口两者结果形态不同均可参考 PhysicsDirectSpaceState2D 文档intersect_shape(parameters, max_results 32)返回Array[Dictionary]每个字典包含collider、collider_id、rid、shape四个字段与结果对象的方法一一对应但每次调用都会分配新数组intersect_shape_into(parameters, result)返回bool把数据写入调用方持有的PhysicsIntersectShapeResult2D。维度intersect_shape()intersect_shape_into() PhysicsIntersectShapeResult2D返回形式字典数组每次分配预分配结果对象可复用命中上限max_results参数max_intersections属性典型场景偶尔查询、代码简洁优先每帧/高频查询、追求低分配失败信号空数组返回false高频物理查询如每帧执行的角色脚下探测、持续性的范围感知建议优先使用intersect_shape_into()加结果对象复用的组合以减少每帧的对象分配与 GC 压力。查询参数细节影响结果的六个开关结果对象本身只负责存储命中哪些对象由PhysicsShapeQueryParameters2D决定。理解以下参数能精确控制PhysicsIntersectShapeResult2D里装入什么shape与shape_ridshape持有Shape2D资源引用文档明确建议优先使用它因为它持有实际引用、避免形状在查询期间被释放shape_rid则用于走 Servers API 的高性能路径可用PhysicsServer2D.circle_shape_create()等创建服务器形状后直接赋值transform查询形状在全局坐标中的Transform2D决定形状的位置与旋转查询使用的是全局坐标而非节点局部坐标collision_mask以位掩码指定要检测的物理层默认4294967295表示全层检测collide_with_areas/collide_with_bodies默认false/true即默认只命中PhysicsBody2D类对象需要把Area2D也纳入结果时必须显式打开collide_with_areasexclude从结果中剔除指定 RID 的对象典型用途是查询发起者自身避免自命中margin形状的碰撞边距默认0.0调大边距会使查询形状在物理上变胖用于容忍微小间隙的探测场景。调用时机为什么必须在 _physics_process 内查询ray-casting 教程 明确指出Godot 物理默认与游戏逻辑同线程运行但也可配置为独立线程因此访问空间状态的安全时机仅限于Node._physics_process()回调从该函数之外访问可能因空间处于锁定状态而报错。这一约束同样适用于使用PhysicsIntersectShapeResult2D的intersect_shape_into()查询。若确需在_input()等时机做形状探测应先把查询意图记录下来延迟到下一个_physics_process()中执行。3D 对应类PhysicsIntersectShapeResult3D2D 与 3D 的物理查询 API 保持对称。3D 空间中的对应结果是 PhysicsIntersectShapeResult3D它拥有完全相同的属性与五个方法max_intersections、get_collider、get_collider_id、get_collider_rid、get_collider_shape、get_intersection_count由 PhysicsDirectSpaceState3D.intersect_shape_into() 填充查询参数则对应为PhysicsShapeQueryParameters3D。换言之理解本文的 2D 结果对象后迁移到 3D 只需替换类名与坐标系类型。一个值得注意的差异PhysicsDirectSpaceState3D.intersect_shape_into()的方法说明中额外注明该方法不考虑motion属性This method does not take into account the motion property of the object。在 2D 的对应方法文档中未见此限制但在依赖motion做扫掠式sweep查询时仍应优先使用专门的cast_motion/cast_motion_into流程。典型应用场景PhysicsIntersectShapeResult2D适合一切用一个形状去探测一片区域内的所有对象的需求技能/武器命中判定在角色面前生成扇形或圆形查询形状一次性取回所有被击中的敌人再按get_collider_id()去重AI 感知以圆形或锥形形状模拟视野/听觉范围每帧把范围内的玩家与友军装入结果对象道具拾取与交互在交互点放置小圆形查询形状检测玩家是否站在可交互物附近地形/平台探测角色脚下放置胶囊或矩形探测形状判断脚下是否有可站立表面配合collide_with_bodies true、exclude [self]群体验证结合max_intersections设定上限只关心范围内是否超过 N 个敌人这类阈值判断提前结束处理。以上场景都能复用同一套模式构建PhysicsShapeQueryParameters2D→ 调用intersect_shape_into()→ 判读返回值 → 遍历get_intersection_count()逐条读取。延伸阅读PhysicsIntersectShapeResult2D 类参考本文主文档属性与方法签名权威出处PhysicsDirectSpaceState2D 类参考查询入口intersect_shape_into()及其姊妹查询方法PhysicsShapeQueryParameters2D 类参考查询参数的全部属性与默认值PhysicsIntersectShapeResult3D 类参考3D 对称实现Ray-casting 教程空间状态获取、_physics_process调用约束与exclude用法CollisionObject2D 类参考get_rid()与碰撞层/掩码相关接口PhysicsDirectSpaceState2DExtension 类参考自定义物理服务器接入时的空间状态扩展点。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐douyin-downloader 抖音无水印下载完整指南3 步完成首次批量下载douyin downloader 抖音无水印下载完整指南3 步完成首次批量下载 douyin downloader 是一款免费的抖音无水印下载工具粘贴视频文档教程游戏开发Godot Shape2D 详解2D 物理碰撞形状基类、自定义 Solver Bias 与碰撞检测 API 实战Godot Shape2D 详解2D 物理碰撞形状基类、自定义 Solver Bias 与碰撞检测 API 实战 Shape2D 是 Godot 引擎中所有文档教程游戏开发k-skill lotto-results:第三方商标在查询型技能中的合规使用边界与实现佐证k skill lotto results:第三方商标在查询型技能中的合规使用边界与实现佐证 本文围绕 lotto results 技能的商标法律声明 http后端即时通讯API设计上一篇JetBrains IDE 试用期重置终极方案告别30天限制的完整指南下一篇DLSS Swapper深度解析三分钟掌握游戏超采样文件管理技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考