Sprite2D

继承： Node2D < CanvasItem < Node < Object

通用精灵节点。

描述

显示 2D 纹理的节点。显示的纹理可以是较大图集纹理中的某个区域，也可以是精灵表动画中的某一帧。

教程

• 实例化演示

属性

bool	centered	true
bool	flip_h	false
bool	flip_v	false
int	frame	0
Vector2i	frame_coords	Vector2i(0, 0)
int	hframes	1
Vector2	offset	Vector2(0, 0)
bool	region_enabled	false
bool	region_filter_clip_enabled	false
Rect2	region_rect	Rect2(0, 0, 0, 0)
Texture2D	texture
int	vframes	1

方法

Rect2	get_rect() const
bool	is_pixel_opaque(pos: Vector2) const

---

信号

frame_changed() 🔗

当 frame 更改时发出。

---

texture_changed() 🔗

当 texture 更改时发出。

---

属性说明

bool centered = true 🔗

• void set_centered(value: bool)

• bool is_centered()

如果为 true，则会将纹理居中。

注意：像素风游戏中，纹理在居中后可能会变形。这是因为此时纹理的位置在两个像素之间。要避免这种情况，请将该属性设为 false，或者考虑启用 ProjectSettings.rendering/2d/snap/snap_2d_vertices_to_pixel 和 ProjectSettings.rendering/2d/snap/snap_2d_transforms_to_pixel。

---

bool flip_h = false 🔗

• void set_flip_h(value: bool)

• bool is_flipped_h()

如果为 true，纹理将被水平翻转。

---

bool flip_v = false 🔗

• void set_flip_v(value: bool)

• bool is_flipped_v()

如果为 true，纹理将被垂直翻转。

---

int frame = 0 🔗

• void set_frame(value: int)

• int get_frame()

当前显示的精灵表中的帧。hframes 和 vframes 必须大于 1。hframes 或 vframes 发生变化时会自动调整该属性，让它在视觉上保持指向同一帧（同一行、同一列）。 如果无法保持，则会重置为 0。

---

Vector2i frame_coords = Vector2i(0, 0) 🔗

• void set_frame_coords(value: Vector2i)

• Vector2i get_frame_coords()

显示的帧在精灵表中的坐标。这是 frame 属性的别名。vframes 或 hframes 必须大于 1。

---

int hframes = 1 🔗

• void set_hframes(value: int)

• int get_hframes()

精灵表中的列数。该属性发生变化时会对 frame 进行调整，在视觉上维持相同的帧（同一行、同一列）。如果无法维持，则会将 frame 重置为 0。

---

Vector2 offset = Vector2(0, 0) 🔗

• void set_offset(value: Vector2)

• Vector2 get_offset()

纹理绘制偏移。

注意：在 Sprite2D 中增大 offset.y 会让精灵在屏幕上向下移动（即 +Y 朝下）。

---

bool region_enabled = false 🔗

• void set_region_enabled(value: bool)

• bool is_region_enabled()

如果为 true，则会从更大的图集纹理上裁剪出纹理。见 region_rect。

注意：对 Sprite2D 使用自定义 Shader 时，着色器内置的 UV 指的是完整纹理空间。请使用内置的 REGION_RECT 获取 region_rect 中定义的当前可见区域。详见《CanvasItem 着色器》。

---

bool region_filter_clip_enabled = false 🔗

• void set_region_filter_clip_enabled(value: bool)

• bool is_region_filter_clip_enabled()

如果为 true，则会裁剪 region_rect 之外的区域，避免周围纹理像素的出血现象。region_enabled 必须为 true。

---

Rect2 region_rect = Rect2(0, 0, 0, 0) 🔗

• void set_region_rect(value: Rect2)

• Rect2 get_region_rect()

要显示的图集纹理区域。region_enabled 必须是 true。

---

Texture2D texture 🔗

• void set_texture(value: Texture2D)

• Texture2D get_texture()

要绘制的 Texture2D 对象。

---

int vframes = 1 🔗

• void set_vframes(value: int)

• int get_vframes()

精灵表中的行数。该属性发生变化时会对 frame 进行调整，在视觉上维持相同的帧（同一行、同一列）。如果无法维持，则会将 frame 重置为 0。

---

方法说明

Rect2 get_rect() const 🔗

返回代表该 Sprite2D 边界的 Rect2，使用局部坐标。

示例：检测该 Sprite2D 是否被点击：

GDScriptC#

func _input(event):
    if event is InputEventMouseButton and event.pressed and event.button_index == MOUSE_BUTTON_LEFT:
        if get_rect().has_point(to_local(event.position)):
            print("我点！")

---

bool is_pixel_opaque(pos: Vector2) const 🔗

Returns true if the pixel at the given position is opaque, false otherwise. Also returns false if the given position is out of bounds or this sprite's texture is null. pos is in local coordinates.