文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载Sprite3D是 Godot Engine 中用于在 3D 场景里显示 2D 纹理的核心节点继承自SpriteBase3D自身提供图集atlas与精灵表sprite sheet相关的帧控制能力。本文基于官方文档类参考页 class_Sprite3D 及其父类 SpriteBase3D 的完整定义展开读完后你将掌握Sprite3D的 7 个自有属性、2 个信号的用法与默认值了解frame/hframes/vframes之间的联动调整规则以及region_enabled/region_rect区域裁剪的工作方式并能结合pixel_size、billboard、alpha_cut等父类属性把它用在3D 场景中的 2D 游戏、远景 impostor 替身等实战场景。继承体系与节点定位Sprite3D的完整继承链为Sprite3D └─ SpriteBase3D └─ GeometryInstance3D └─ VisualInstance3D └─ Node3D └─ Node └─ Object来源class_sprite3d.rst 第 13 行的 Inherits 声明官方对Sprite3D的定义是A node that displays a 2D texture in a 3D environment. The texture displayed can be a region from a larger atlas texture, or a frame from a sprite sheet animation.在 3D 环境中显示 2D 纹理的节点纹理可以是更大图集纹理的一部分区域也可以是精灵表动画中的一帧。这条继承链决定了Sprite3D的能力边界SpriteBase3Dclass_spritebase3d.rst定义所有在 3D 中绘制 2D 纹理的公共能力——billboard 模式、像素大小、透明度/阴影绘制标志、Alpha Cut 模式等它同时是 AnimatedSprite3D 的父类即Sprite3D与AnimatedSprite3D是兄弟节点共享同一套底层绘制标志体系。GeometryInstance3D提供material_override材质覆盖、cast shadow 以及 visibility range可见距离区间等能力。正因如此可见距离HLOD教程 指出 visibility range 可用于所有继承GeometryInstance3D的节点并给出典型用例——近处用MeshInstance3D表示一棵树远处替换为Sprite3Dimpostor假面片以提升性能。核心用法3D 世界中的 2D 游戏官方 Introduction to 3D 在2D in 3D小节明确给出了Sprite3D的标准应用场景使用固定不旋转的正交或透视相机Sprite3D与AnimatedSprite3D可以用来创建 2D 游戏同时享受与 3D 背景混合、更真实的视差、光照/阴影效果等。代价是相比纯 2D 引擎多出复杂度与性能开销且失去了按像素工作的直观参考。另一个常见用法见于 Area light 章节AreaLight3D节点本身只在场景中发光、没有可见形态官方文档就使用一个Sprite3D作为其子节点来做可视化标记。自有属性详解frame / frame_coords / hframes / vframesSprite3D在父类之上新增 7 个属性完整列表见 class_sprite3d.rst 的 Properties 表类型属性默认值intframe0Vector2iframe_coordsVector2i(0, 0)inthframes1intvframes1boolregion_enabledfalseRect2region_rectRect2(0, 0, 0, 0)Texture2Dtexture空frame当前显示的精灵表帧类型int默认0setterset_frame(value: int)getterget_frame()。官方描述Current frame to display from sprite sheet.显示精灵表中的当前帧使用前提hframes或vframes必须大于 1否则没有多帧可切换。联动规则这是官方文档明确写出的关键行为当hframes或vframes发生变化时frame会被自动调整尽量保持指向同一个视觉帧即同一行、同一列如果做不到则重置为0。hframes / vframes精灵表的列数与行数类型int默认均为1setter 分别为set_hframes(value)/set_vframes(value)。hframes是精灵表的列数columnsvframes是行数rows。与frame的联动规则与上文相同改变行列数时frame会调整以保持同一视觉帧无法保持时重置为0。frame_coordsframe 的行列坐标别名类型Vector2i默认Vector2i(0, 0)setterset_frame_coords(value)getterget_frame_coords()。官方描述它是frame属性的别名alias用 (列, 行) 坐标表达同一概念同样要求hframes或vframes大于 1。三者关系可以这样理解frame是按行主序展开的一维索引frame_coords是二维坐标形式hframes/vframes决定了网格的行列规模。region_enabled / region_rect图集区域裁剪region_enabledbool默认falsesetterset_region_enabled(value)getter 为is_region_enabled()注意 getter 命名与其他属性的get_xxx()惯例不同。region_rectRect2默认Rect2(0, 0, 0, 0)setterset_region_rect(value)getterget_region_rect()。官方描述当region_enabled为true时精灵使用region_rect定义的区域只显示纹理中指定的那一部分。region_rect只有在region_enabled true时才生效The region of the atlas texture to display.要显示的图集纹理区域。texture要绘制的 Texture2D类型Texture2D无默认值setterset_texture(value)getterget_texture()。官方描述附带一个重要注意点若使用了GeometryInstance3D.material_overridetexture会被覆盖但尺寸信息仍会被使用The size information is still used.。也就是说材质覆盖改变外观时Sprite3D的几何尺寸仍依据原texture的大小计算。信号Sprite3D定义了两个信号信号触发时机frame_changed()frame变化时发出texture_changed()texture变化时发出在 GDScript 中监听这两个信号的典型写法# 监听精灵表切帧例如驱动帧动画的辅助逻辑 sprite_3d.frame_changed.connect(_on_frame_changed) sprite_3d.texture_changed.connect(_on_texture_changed) func _on_frame_changed() - void: print(当前帧: , sprite_3d.frame)父类关键能力让 Sprite3D 真正可用的属性SpriteBase3Dclass_spritebase3d.rst承载了Sprite3D的大部分渲染行为实战中几乎总会用到。完整属性表含默认值类型属性默认值说明floatalpha_antialiasing_edge0.0Alpha 通道抗锯齿应用的阈值AlphaAntiAliasingalpha_antialiasing_mode0Alpha 抗锯齿类型AlphaCutModealpha_cut0Alpha 裁剪模式floatalpha_hash_scale1.0Alpha Hash 的哈希比例推荐 0~2floatalpha_scissor_threshold0.5Alpha scissor 丢弃值的阈值Axisaxis2纹理正面朝向的方向轴BillboardModebillboard0广告牌billboard模式boolcenteredtrue纹理是否居中booldouble_sidedtrue背面是否可见boolfixed_sizefalse是否保持屏幕固定大小boolflip_h/flip_vfalse水平/垂直翻转ColormodulateColor(1, 1, 1, 1)与纹理颜色相乘的调制色boolno_depth_testfalse禁用深度测试按渲染顺序绘制Vector2offsetVector2(0, 0)纹理绘制偏移floatpixel_size0.01精灵上单个像素的宽度3D 缩放基准intrender_priority0透明物体间的渲染优先级boolshadedfalse是否受场景中 Light3D 影响TextureFiltertexture_filter3纹理过滤标志booltransparenttrue是否使用纹理的透明通道几个高频属性的要点均出自 class_spritebase3d.rstpixel_sizeThe size of one pixels width on the sprite to scale it in 3D. 默认0.01即纹理每 1 像素对应 0.01 米——这是把 2D 贴图放进 3D 世界尺度的关键参数。billboardThe billboard mode to use for the sprite.默认0不启用。文档同时给出警告billboard 启用且材质投射阴影时billboard 面向的是场景相机多相机场景下阴影行为未定义。fixed_size为true时纹理无视距离始终保持同一屏幕大小——The textures size on screen is the same as if the camera was 1.0 units away from the textures origin等效于相机距纹理原点 1.0 单位时的屏幕大小相机的 FOV或正交模式下的Camera3D.size仍会影响绘制大小。modulate与纹理颜色做乘法可用于氛围染色或模拟环境光颜色注意与 2DCanvasItem.modulate不同不支持大于 1.0 的 overbright 值。另一条重要约束若节点上定义了material_override材质必须配置为把顶点色计入 albedoBaseMaterial3D需将vertex_color_use_as_albedo设为trueShaderMaterial需在fragment()中写入ALBEDO * COLOR.rgb;否则modulate会被忽略。render_priority优先级高的透明物体排在前但文档明确两个前提——仅当alpha_cut为默认的ALPHA_CUT_DISABLED时生效且只影响透明物体之间的排序不影响透明/不透明物体之间的排序。offset纹理绘制偏移文档特别指出在Sprite3D中增大offset.y会使精灵沿世界 Y 方向向上移动。绘制标志与 DrawFlags 枚举SpriteBase3D提供一对方法set_draw_flag(flag: DrawFlags, enabled: bool) - void get_draw_flag(flag: DrawFlags) - bool # constDrawFlags枚举值class_spritebase3d.rst常量值含义FLAG_TRANSPARENT0使用纹理透明度与不透明度使精灵对应部分不可见FLAG_SHADED1场景光照影响精灵FLAG_DOUBLE_SIDED2背面可见否则从后方看不可见FLAG_DISABLE_DEPTH_TEST3禁用深度测试绘制在所有物体之上FLAG_FIXED_SIZE4按深度缩放标签使屏幕大小恒定FLAG_MAX5枚举大小这些标志与上表的transparent、shaded、double_sided、no_depth_test、fixed_size属性一一对应——属性是其便捷封装set_draw_flag/get_draw_flag是底层开关。AlphaCutMode透明排序的四种解法alpha_cut属性决定Sprite3D处理透明的方式枚举定义见 class_spritebase3d.rst常量值行为ALPHA_CUT_DISABLED0默认标准 alpha 混合可显示半透明区域但多个透明物体重叠时可能出现排序问题ALPHA_CUT_DISCARD1只允许全透明或全不透明像素即 alpha testing / 1-bit transparency无透明排序问题但边缘生硬需开启屏幕空间抗锯齿ALPHA_CUT_OPAQUE_PREPASS2全不透明像素走深度预通道比前两种慢但可显示半透明区域与平滑边缘且排序正确ALPHA_CUT_HASH3按空间确定性阈值裁剪低于阈值的全部裁掉其余保持不透明配合alpha_hash_scale调节官方 3D text 教程 说明了这类透明 quad 的共性局限Label3D内部生成的 quad mesh has the same limitations as Sprite3D与 Sprite3D 具有相同的局限性当多个透明精灵重叠时透明排序问题会显现可改用Alpha Cut缓解代价是渲染平滑度下降Opaque Pre-Pass能保留平滑度并允许投射阴影但仍残留少量排序问题。生成网格generate_triangle_mesh 与 get_item_rectSpriteBase3D还提供两个查询方法TriangleMesh generate_triangle_mesh()const返回一个TriangleMesh其顶点遵循精灵当前的配置包括axis与pixel_size。这意味着你可以在运行时把Sprite3D当前的几何形状导出为真实网格例如用于生成碰撞体或转成MeshInstance3D。Rect2 get_item_rect()const返回表示该精灵的矩形区域。与 AnimatedSprite3D 的关系选哪个节点Sprite3D是单纹理节点一张Texture2D通过frame/hframes/vframes或region_rect选择要显示的子区域。需要真正的多帧动画时应使用同父类的 AnimatedSprite3D其官方描述为AnimatedSprite3Dis similar to the Sprite3D node, except it carries multiple textures as animation sprite_frames. Animations are created using a SpriteFrames resource…即动画帧由SpriteFrames资源承载提供play()/pause()/stop()/play_backwards()等播放控制方法与animation_changed/animation_finished/animation_looped等信号。选择原则静态图片、图集区域展示、手动切帧如代码驱动的帧序列→Sprite3D由资源管理多段命名动画、需要播放控制 →AnimatedSprite3D。两者共享SpriteBase3D的全部绘制属性切换节点类型时视觉配置基本可以平移。实战示例带精灵表与 billboarding 的 3D 精灵综合本文属性一个可运行的最小示例3D 场景根节点为Node3D# 在场景树中Node3D - Sprite3D挂 4x2 的精灵表纹理 var sprite: Sprite3D $Sprite3D func _ready() - void: # 精灵表4 列 2 行 sprite.hframes 4 sprite.vframes 2 # 每像素 0.01 米默认值如需更大精灵可上调如 0.05 sprite.pixel_size 0.01 # 始终面向相机的 billboard 由 billboard 属性设置编辑器中可选 Y 轴等模式 # 监听切帧信号做代码驱动的帧序列 sprite.frame_changed.connect(_on_frame_changed) sprite.frame 0 var _t: float 0.0 var _next: float 0.0 func _process(delta: float) - void: # 0.1 秒切一帧行内循环 _t delta if _t _next: _next 0.1 sprite.frame (sprite.frame 1) % (sprite.hframes * sprite.vframes) func _on_frame_changed() - void: # 例如根据帧更新偏移或 modulate sprite.modulate Color(1.0, 1.0, 1.0, 1.0)使用region_enabled/region_rect的图集裁剪示例# 从一张大贴图中只取左上角 64x64 区域 sprite.region_enabled true sprite.region_rect Rect2(0, 0, 64, 64)注意修改hframes/vframes后frame会按保持同一视觉帧的规则自动调整无法保持时归零见上文联动规则frame_coords是等价的行列坐标写法例如sprite.frame_coords Vector2i(2, 1)指向第 3 列第 2 行。关键限制与注意事项汇总以下限制均来自仓库文档原文实战前建议逐条核对材质覆盖的纹理替换语义material_override会覆盖texture的外观但几何尺寸仍取自原纹理class_sprite3d.rst。modulate 不支持 overbright与 2D 的CanvasItem.modulate不同颜色分量 1.0 不被支持且材质覆盖时须显式启用顶点色作为 albedo 才能看到modulate效果。透明排序问题多个透明Sprite3D重叠时会出现排序瑕疵可用ALPHA_CUT_DISCARD或ALPHA_CUT_OPAQUE_PREPASS缓解3d_text.rst 的 Label3D 章节同样引用了这一 Sprite3D 共性局限。render_priority 的适用边界仅在alpha_cut ALPHA_CUT_DISABLED且仅影响透明物体之间排序时有效。billboard 阴影的多相机未定义行为开启 billboard 且投射阴影时多相机场景下阴影朝向未定义class_spritebase3d.rstbillboard条目警告。linear 过滤的边缘伪影texture_filter使用线性过滤时纹理边缘附近可能出现伪影不透明纹理尤其明显建议边缘使用透明或同色像素texture_filter条目 Note。延伸阅读仓库内相关页面SpriteBase3D 类参考billboard、DrawFlags、AlphaCutMode 的完整定义。AnimatedSprite3D 类参考多帧动画与 SpriteFrames 资源。Introduction to 3D — 2D in 3DSprite3D用于 2D-in-3D 游戏的官方推荐场景。Visibility ranges (HLOD)把Sprite3D作为远景 impostor 的性能优化用法。Lights and shadows — Area light用Sprite3D可视化AreaLight3D的示例。赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot 3D 精灵实战指南用 Sprite3D 与 AnimatedSprite3D 在三维世界中渲染 2D 资产godot-demo-projects 的 3d/sprites 演示解析Godot 3D 精灵实战指南用 Sprite3D 与 AnimatedSprite3D 在三维世界中渲染 2D 资产godot demo projects示例工程Godot Sprite2D 类详解纹理显示、精灵图帧动画与图集区域裁剪Godot Sprite2D 类详解纹理显示、精灵图帧动画与图集区域裁剪 本文以 Godot 官方文档仓库中的 Sprite2D 类参考页 https://l文档教程游戏开发Godot 官方文档精读AnimatedSprite3D 节点——在 3D 世界中使用 SpriteFrames 驱动 2D 序列帧动画Godot 官方文档精读AnimatedSprite3D 节点——在 3D 世界中使用 SpriteFrames 驱动 2D 序列帧动画 导读 Anima文档教程游戏开发上一篇10个必知的DevSecOps容器安全工具microscanner、kube-bench等K8s安全防护终极指南下一篇10个必学的计算机视觉实战项目 - L0CV平台深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考