Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

RayCast2D

继承： Node2D < CanvasItem < Node < Object

2D 空间中的射线，用于查找第一个相交的 CollisionObject2D。

描述

Raycast 代表的是从它的原点到 target_position 的射线，如果与碰撞对象相交，就能找到路径上距离最近的 CollisionObject2D。

要让 RayCast2D 忽略某些对象，可以通过将它们加入例外列表，也可以通过让检测汇报忽略 Area2D（collide_with_areas）或 PhysicsBody2D（collide_with_bodies），还可以通过配置物理层。

RayCast2D 每一个物理帧都会计算是否相交，且该计算结果会保留到下一个物理帧。如果要立即执行射线投射，或者你想要在同一个物理帧内多次配置 RayCast2D，请使用 force_raycast_update()。

要扫描 2D 空间中的某个区块，可以使用多个 RayCast2D 或使用 ShapeCast2D 去近似该区块。

教程

属性

bool

collide_with_areas

false

bool

collide_with_bodies

true

int

collision_mask

1

bool

enabled

true

bool

exclude_parent

true

bool

hit_from_inside

false

Vector2

target_position

Vector2(0, 50)

方法

void

add_exception(node: CollisionObject2D)

void

add_exception_rid(rid: RID)

void

clear_exceptions()

void

force_raycast_update()

Object

get_collider() const

RID

get_collider_rid() const

int

get_collider_shape() const

bool

get_collision_mask_value(layer_number: int) const

Vector2

get_collision_normal() const

Vector2

get_collision_point() const

bool

is_colliding() const

void

remove_exception(node: CollisionObject2D)

void

remove_exception_rid(rid: RID)

void

set_collision_mask_value(layer_number: int, value: bool)

属性说明

bool collide_with_areas = false 🔗

  • void set_collide_with_areas(value: bool)

  • bool is_collide_with_areas_enabled()

如果为 true，则会报告与 Area2D 的碰撞。

bool collide_with_bodies = true 🔗

  • void set_collide_with_bodies(value: bool)

  • bool is_collide_with_bodies_enabled()

如果为 true，则会报告与 PhysicsBody2D 的碰撞。

int collision_mask = 1 🔗

  • void set_collision_mask(value: int)

  • int get_collision_mask()

射线的碰撞遮罩。只能检测到至少启用了一个遮罩中碰撞层的对象。详见文档中的《碰撞层与掩码》。

bool enabled = true 🔗

  • void set_enabled(value: bool)

  • bool is_enabled()

如果为 true，将报告碰撞。

bool exclude_parent = true 🔗

  • void set_exclude_parent_body(value: bool)

  • bool get_exclude_parent_body()

如果为 true，父节点将被排除在碰撞检测之外。

bool hit_from_inside = false 🔗

  • void set_hit_from_inside(value: bool)

  • bool is_hit_from_inside_enabled()

如果为 true，射线会在从形状内部开始时检测到命中。在此情况下，碰撞法线将为 Vector2(0, 0)。不会影响凹多边形形状。

Vector2 target_position = Vector2(0, 50) 🔗

  • void set_target_position(value: Vector2)

  • Vector2 get_target_position()

射线的目标点，相对于该 RayCast 的 position。

方法说明

void add_exception(node: CollisionObject2D) 🔗

添加碰撞例外，这样射线就不会报告与指定 CollisionObject2D 节点的碰撞。

void add_exception_rid(rid: RID) 🔗

添加碰撞例外，这样射线就不会报告与指定 RID 的碰撞。

void clear_exceptions() 🔗

删除此射线的所有碰撞例外。

void force_raycast_update() 🔗

立即更新射线的碰撞信息，不等待下一次的 _physics_process 调用。例如，请在射线或其父级更改状态后使用该方法。

注意：enabled 不需要为 true 即可生效。

Object get_collider() const 🔗

返回射线相交的第一个对象，如果没有对象与射线相交，则返回 null（即 is_colliding() 返回 false）。

RID get_collider_rid() const 🔗

返回该射线相交的第一个对象的 RID，如果没有对象与该射线相交，则返回空 RID（即 is_colliding() 返回 false）。

int get_collider_shape() const 🔗

返回与射线相交的第一个对象的形状 ID，射线未与任何对象相交时返回 0（即 is_colliding() 返回 false 时）。

要获取相交的形状节点，比如假设目标是 CollisionObject2D，可以使用：

var target = get_collider() # 是 CollisionObject2D 节点。
var shape_id = get_collider_shape() # 碰撞体中的形状索引。
var owner_id = target.shape_find_owner(shape_id) # 碰撞体中的所有者 ID。
var shape = target.shape_owner_get_owner(owner_id)

bool get_collision_mask_value(layer_number: int) const 🔗

返回 collision_mask 中是否启用了指定的层，给定的 layer_number 应在 1 和 32 之间。

Vector2 get_collision_normal() const 🔗

返回相交对象的形状在碰撞点处的法线，如果射线从该形状内部发出并且 hit_from_inside 为 true，则为 Vector2(0, 0)。

注意：请在调用前检查 is_colliding() 返回的是否为 true，这样返回的法线就是即时有效的。

Vector2 get_collision_point() const 🔗

返回全局坐标系中射线与最近的物体相交的碰撞点。如果 hit_from_inside 为 true 并且射线从碰撞形状内部开始，则该函数将返回该射线的原点。

注意：在调用该方法之前，请检查 is_colliding() 是否返回 true，以确保返回的点有效且最新。

bool is_colliding() const 🔗

返回是否有任何对象与射线的向量相交（考虑向量长度）。

void remove_exception(node: CollisionObject2D) 🔗

移除碰撞例外，这样射线就会报告与指定的 CollisionObject2D 节点的碰撞。

void remove_exception_rid(rid: RID) 🔗

移除碰撞例外，这样射线就会报告与指定的 RID 的碰撞。

void set_collision_mask_value(layer_number: int, value: bool) 🔗

根据 value，启用或禁用 collision_mask 中指定的层，给定的 layer_number 应在 1 和 32 之间。