Godot Sprite2D 完全指南纹理显示、精灵图帧动画与图集裁剪【免费下载链接】godot-docsGodot Engine official documentation项目地址: https://gitcode.com/GitHub_Trending/go/godot-docsGodot 官方文档仓库中Sprite2D参考页classes/class_sprite2d.rst共有 12 个属性、2 个方法、2 个信号。这里按显示姿态、帧动画、图集裁剪三大能力域重新归类帮你在最短时间内搭好自己的 2D 精灵避开常见坑。像素平台跳跃里Sprite2D 解决什么问题你需要让角色动起来Sprite2D负责显示角色贴图跑步时靠hframes/frame换帧转向时靠flip_h掉头落地判定靠get_rect()配合物理。继承链为Object ← Node ← CanvasItem ← Node2D ← Sprite2D。Node2D提供position、rotation、scale变换CanvasItem提供modulate调制、材质、自定义 shader 与光照响应自身增加的只有纹理选择、帧与区域裁剪、翻转和居中控制。官方2D 角色移动教程里CharacterBody2D的子节点正是Sprite2D加CollisionShape2D甚至可以直接拿引擎自带的icon.svg当纹理——这是把Sprite2D用进可玩原型的最小配置。和 AnimatedSprite2D 什么区别AnimatedSprite2D是“自带多帧序列的精灵节点”多组动画帧由SpriteFrames资源管理见classes/class_animatedsprite2d.rst与classes/class_spriteframes.rst。如果你只需要程序化切帧或配合AnimationPlayer做关键帧动画 →Sprite2D如果你要管理多组命名动画、在编辑器里挑选帧 →AnimatedSprite2D。完整对照演示在2D 精灵动画教程的 “Sprite sheet with AnimationPlayer” 一节。显示与姿态texture、centered、flip、offset 四件套texture显示的第一步texture是Sprite2D的根属性类型Texture2D指定要绘制的纹理。不设置时节点什么都不显示依赖纹理的查询如is_pixel_opaque()也会直接返回false。centered像素风的变形陷阱centered默认true以纹理中心为绘制中心。官方文档给过像素风提示纹理中心落在两个像素之间时贴图看起来会变形。解决办法是设为false或启用两个项目设置rendering/2d/snap/snap_2d_vertices_to_pixelrendering/2d/snap/snap_2d_transforms_to_pixel两者在ProjectSettings 参考中默认均为false且有两条使用限制其一只在项目启动时读取运行期切换需对根Viewport调RenderingServer的viewport_set_snap_2d_vertices_to_pixel()/viewport_set_snap_2d_transforms_to_pixel()其二官方不建议同时开启移动可能显得更不流畅二选一、优先snap_2d_transforms_to_pixel。centered还决定旋转枢轴新节点的默认枢轴在(x: 0, y: 0)例外正是Sprite2D——centered为true时枢轴落在纹理中心。见tutorials/2d/introduction_to_2d.rst的视口说明。flip_h / flip_v转向不靠旋转两个布尔开关为true时纹理分别沿水平轴、垂直轴翻转。这是平台游戏“角色左右转向”最常用的手段——比旋转节点 180° 直观且不会把碰撞和光照方向一起转走。2D 精灵动画教程也提到角色转向时平台游戏常同步更新flip_h/flip_v。offset绘制偏移微调offset为Vector2默认Vector2(0, 0)控制纹理的绘制偏移。易混点offset.y增大时精灵在屏幕上向下移动Y 朝下。做“脚底对齐地面”这类微调时记住这一点。精灵图帧动画切帧三步走切帧三步走一张含 6 帧跑动动画的精灵图来自2D 精灵动画教程把精灵图拖入texture属性整张图集一次性显示展开检查器的Animation区域Hframes设为6hframes/vframes对应精灵图水平/垂直方向的帧数默认都是1修改frame取值 0~5显示内容随之逐帧变化——这就是接下来要动画化的目标属性。frame 与 hframes / vframes 的联动规则frame只有配合hframes/vframes才有意义——它需要先知道网格怎么切。官方联动规则修改hframes时frame自动调整保持指向同一个视觉帧同一行、同一列若无法保持如列数减少后原列不存在frame重置为0修改vframes时行为完全对称反向修改frame不受影响但它与frame_coords始终同步——一个线性索引一个(列, 行)坐标两者都要求hframes/vframes大于 1。frame_changed 与 texture_changed 信号Sprite2D只暴露两个信号都是属性变化通知型frame_changed()frame值变化时发射。脚本赋值、检查器修改、动画驱动都算可用于在换帧瞬间联动音效、粒子或程序逻辑texture_changed()texture变化时发射适合“换装、状态切换后监听贴图被替换”的场景。两者都不带参数接收方需自行回读属性拿最新值。图集裁剪怎么防渗色region 三件套多张小图打进一张大图集atlas texture时Sprite2D可以只绘制其中一块region_enabledbool默认false开关为true表示纹理从更大的图集裁剪而来region_rectRect2默认Rect2(0, 0, 0, 0)要显示的图集区域要求region_enabled为trueregion_filter_clip_enabledbool默认false把region_rect之外的区域裁剪掉避免周围纹理像素渗色bleeding同样要求region_enabled为true。shader 里 UV 与 REGION_RECT 的采样坑官方文档记录了明确的坑在Sprite2D上使用自定义 Shader 时UV内建变量引用的是整个纹理空间要拿region_rect定义的当前可见区域应改用REGION_RECT内建变量。CanvasItem Shader 参考对REGION_RECT的取值有精确说明in vec4类型(x, y, width, height)格式随region_enabled变化数值经过归一化——例如 1000×800 纹理上偏移 (100, 100)、大小 600×400 的区域对应vec4(0.1, 0.125, 0.6, 0.5)。X/Y 偏移为负或区域尺寸超过纹理尺寸时各分量可能超出 0.0~1.0 范围。实战工作流用 AnimationPlayer 播放帧动画以 6 帧跑动精灵图为例场景结构是CharacterBody2D也可用Area2D/RigidBody2D作根节点下挂Sprite2DAnimationPlayer精灵图拖入textureHframes设6在AnimationPlayer新建动画walk时长0.6秒勾选循环选中Sprite2D点关键帧图标添加轨道沿时间轴按每0.1秒打满 0~5 的帧关键帧。轨道打满后的效果脚本控制沿用play()/stop()标准写法按住右箭头播放、松开停止extends CharacterBody2D onready var _animation_player $AnimationPlayer func _process(_delta): if Input.is_action_pressed(ui_right): _animation_player.play(walk) else: _animation_player.stop()C# 对应实现using Godot; public partial class Character : CharacterBody2D { private AnimationPlayer _animationPlayer; public override void _Ready() { _animationPlayer GetNodeAnimationPlayer(AnimationPlayer); } public override void _Process(double delta) { if (Input.IsActionPressed(ui_right)) _animationPlayer.Play(walk); else _animationPlayer.Stop(); } }play() 的时序细节教程记录了值得注意的细节play()并非即时生效而是在AnimationPlayer下一次被处理时应用可能已经是下一帧。若同一帧内同时改动了flip_h/flip_v会出现“属性已变、动画未变”的错帧。解法在play()之后追加advance(0)立即刷新动画。命中判定get_rect 矩形判定 vs is_pixel_opaque 逐像素判定get_rect()点击命中怎么做Rect2 get_rect()是 const 方法返回表示Sprite2D边界在本地坐标系中的Rect2考虑了纹理尺寸与centered。官方标准示例是点击检测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(A click!)C# 版本public override void _Input(InputEvent event) { if (event is InputEventMouseButton inputEventMouse) { if (inputEventMouse.Pressed inputEventMouse.ButtonIndex MouseButton.Left) { if (GetRect().HasPoint(ToLocal(inputEventMouse.Position))) { GD.Print(A click!); } } } }关键是to_local(event.position)get_rect()返回本地坐标下的矩形而_input收到的是视口坐标不转换就没法直接比较。注意该矩形基于纹理尺寸而非不透明像素点透明区域也算命中。is_pixel_opaque()像素级判定bool is_pixel_opaque(pos: Vector2)是 const 方法给定本地坐标pos处像素不透明时返回true。返回false的边界条件有两种位置超出精灵范围out of bounds或该精灵的texture为null。它适合“踩到透明格子不触发”“只命中可见像素”这类逻辑是get_rect()矩形判定的精细化补充。易错点清单⚠️ 像素风 centeredtrue→ 贴图变形。解法centered设false或启用 snap 设置且只开一个优先snap_2d_transforms_to_pixel。⚠️ 改了frame但显示不变。原因hframes/vframes还是1。解法先设行列切分再改frame。⚠️ 点到透明区域也算命中。解法改用is_pixel_opaque(to_local(position))做逐像素判定。⚠️ 点击永远判不中。原因视口坐标直接和get_rect()的本地矩形比较。解法先to_local(event.position)再参与has_point()。⚠️ 换帧瞬间“属性已变、动画未变”。解法play()后调用advance(0)立即刷新动画。⚠️ 开启 region 后 shader 里UV采到整张纹理。解法改用REGION_RECT内建变量采样区域。⚠️ 设了region_rect/region_filter_clip_enabled却不生效。原因region_enabled不是true。解法先开开关再设区域。⚠️ 把Sprite2D.get_rect()和 4.x 的Image.get_region()搞混。原因旧Image类的get_rect()在 4.x 更名get_region()是不同类上的不同方法见4.x 升级指南阅读升级文档时别混淆。速查属性读写与信号速查表想做什么用什么设置 / 读取要绘制的纹理set_texture(value: Texture2D)/get_texture() - Texture2D设置 / 读取居中绘制set_centered(value: bool)/is_centered() - bool设置 / 读取水平翻转set_flip_h(value: bool)/is_flipped_h() - bool设置 / 读取垂直翻转set_flip_v(value: bool)/is_flipped_v() - bool设置 / 读取当前帧索引set_frame(value: int)/get_frame() - int设置 / 读取帧坐标 (列, 行)set_frame_coords(value: Vector2i)/get_frame_coords() - Vector2i设置 / 读取精灵图列数set_hframes(value: int)/get_hframes() - int设置 / 读取精灵图行数set_vframes(value: int)/get_vframes() - int设置 / 读取绘制偏移set_offset(value: Vector2)/get_offset() - Vector2设置 / 读取图集区域开关set_region_enabled(value: bool)/is_region_enabled() - bool设置 / 读取显示区域矩形set_region_rect(value: Rect2)/get_region_rect() - Rect2设置 / 读取区域裁剪开关set_region_filter_clip_enabled(value: bool)/is_region_filter_clip_enabled() - bool监听换帧联动音效/粒子frame_changed()信号无参数自行回读frame监听纹理被替换换装等texture_changed()信号无参数自行回读texture下一步需要多组命名动画、随机或程序化帧序列 → 升级到AnimatedSprite2DSpriteFrames方案完整对比见2D 精灵动画教程把Sprite2D接上物理、写出角色移动与跳跃 → 2D 角色移动教程想给精灵写自定义效果 → 从CanvasItem Shader 参考入手重点留意UV与REGION_RECT的采样范围差异。【免费下载链接】godot-docsGodot Engine official documentation项目地址: https://gitcode.com/GitHub_Trending/go/godot-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
