游戏引擎 / 系统课时
用射线检测准星命中的物体
用射线检测准星命中的物体
玩家把准星对准宝箱时,游戏需要知道视线首先碰到了什么,而不是只判断附近是否有宝箱。本课用 Godot 4 的三维物理射线,从摄像机中心查询最多 3 米内的碰撞物,并让 E 键只对当前可见的交互目标生效。
学习目标
- 理解摄像机前向、射线距离与首次命中的关系。
- 使用
intersect_ray()识别带碰撞体的交互对象。 - 排除玩家自身碰撞体,并验证墙壁遮挡和交互距离。
准星为什么对应一条射线
屏幕中央准星代表摄像机的观察方向。在 Godot 3D 中,摄像机局部 -Z 是前方;把 camera.global_position 作为起点,沿 -camera.global_transform.basis.z 延伸指定距离,就得到世界坐标下的查询线段。
intersect_ray() 返回沿线段遇到的第一个碰撞结果,包含 collider、position、normal 等信息;未命中时返回空字典。因此要让墙壁也参与查询,不能只查询宝箱,否则可能隔墙操作。

准备节点和碰撞过滤
在已有的 Player(CharacterBody3D) 下放置同级子节点 Camera3D 与 Interactor(Node3D),将下方脚本挂在 Interactor 上。这样不会覆盖角色已有的移动脚本,且能读取同级摄像机的朝向。
场景中的交互宝箱命名为 Chest,使用 StaticBody3D 作为根,添加配置了形状资源的 CollisionShape3D,把 Chest 根节点加入 interactable 组,并将其物理碰撞层设为第 2 层。墙壁、地板和玩家位于第 1 层;查询掩码 3 同时包含这两层。最后在项目的 Input Map 中建立动作 interact,绑定 E 键。
在物理帧查询当前目标
PhysicsDirectSpaceState3D 适合按需执行即时射线查询。物理空间访问放在 _physics_process() 中;每次先清空旧目标,再根据最新命中结果更新,避免玩家移开准星后仍能操作上一次的宝箱。
extends Node3D
@export var max_distance: float = 3.0
@onready var camera: Camera3D = $"../Camera3D"
@onready var player: CharacterBody3D = get_parent() as CharacterBody3D
var aimed_target: CollisionObject3D
func _physics_process(_delta: float) -> void:
var origin := camera.global_position
var to_point := origin - camera.global_transform.basis.z * max_distance
# 掩码 3 包含墙壁所在的层 1 和宝箱所在的层 2。
var query := PhysicsRayQueryParameters3D.create(origin, to_point, 3)
query.exclude = [player.get_rid()] # 忽略玩家自己的碰撞体
var hit := get_world_3d().direct_space_state.intersect_ray(query)
aimed_target = null
if not hit.is_empty():
var collider := hit["collider"] as CollisionObject3D
if collider != null and collider.is_in_group("interactable"):
aimed_target = collider
# 只在按键刚按下时响应,避免连续触发。
if aimed_target != null and Input.is_action_just_pressed("interact"):
print("交互目标:", aimed_target.name)预期输出(站在 3 米内、无遮挡地瞄准 Chest 并按一次 E):
交互目标:Chestget_rid() 用于排除角色物理体;is_in_group() 用于把命中的普通墙壁和可交互对象区分开。这里只打印目标名称,后续可把打印替换成调用宝箱的交互方法。
验证遮挡与常见失效原因
先在宝箱前按 E,确认输出一次;随后退到 3 米外再按 E,应该没有输出;最后把带碰撞形状的墙壁放在摄像机与宝箱之间,按 E 同样不应触发。移开准星后也不应沿用旧目标。
如果始终无法命中,检查 Chest 的碰撞形状是否启用、第 2 层是否勾选,以及 interactable 组是否加在真正被射线击中的 StaticBody3D 上,而不是仅加在它的网格子节点上。若需要检测 Area3D,还要显式设置 query.collide_with_areas = true;默认射线只检测物理实体。