Godot 2D 角色放进 3D 场景

用 Sprite3D、SubViewport 把 2D 美术放进真 3D 场景，配 Environment 做 HD-2D 观感。

标了实测的条目来自 4.7.2 软件渲染读像素，Compatibility 与 Forward+ 两个渲染器，方法见 references/render-check.md。

范围

先查内置

做法

路线选择

• 要旋转镜头、动态光影、雾、景深任一项，走真 3D
• 只要前景大后景小，手算缩放更省事
• 中途换路线要重做美术摆放与相机

Sprite3D 配置

extends Sprite3D

func _ready() -> void:
	pixel_size = 1.0 / 32.0
	billboard = BaseMaterial3D.BILLBOARD_FIXED_Y
	texture_filter = BaseMaterial3D.TEXTURE_FILTER_NEAREST
	alpha_cut = SpriteBase3D.ALPHA_CUT_DISCARD
	shaded = true
	var used := texture.get_image().get_used_rect()
	offset.y = used.end.y - texture.get_height() * 0.5

• offset 单位是贴图像素，脚底要对准不透明脚底行
• 贴图底部常留透明行，取半个高度会让脚悬空
• Image.get_used_rect() 的 end.y 是最后不透明行的下沿
• offset.y 取它减半个高度，上例只适用单帧贴图
• 精灵表按帧区域量；写 .tscn 时用脚本或 PIL 读像素算出常数
• TextureAtlas 导入类型只支持 2D，不能给 Sprite3D 用

billboard

• 俯仰角 p 下 FIXED_Y 屏幕高度乘 cos p，ENABLED 不缩短
• 保持原高：scale.y 设为 1 除以 cos p
• billboard 下绕 Y 的朝向由相机决定，父节点转 180 度无效，实测
• ENABLED 绕原点后仰，原点在中心时下沿抬离地面
• 角色用 FIXED_Y，原点放脚底

朝向翻转

只用 flip_h，AnimatedSprite3D 同样有。

extends AnimatedSprite3D

func face(direction_x: float) -> void:
	if direction_x != 0.0:
		flip_h = direction_x < 0.0

• billboard 下 scale.x = -1 不翻转，父节点转向或负缩放也无效，实测
• 负缩放加 double_sided = false 时，ENABLED 下精灵被背面剔除消失
• 非 billboard 下负缩放可以翻转

alpha_cut 与阴影

• 像素风角色选 DISCARD，半透明羽化边才选 OPAQUE_PREPASS
• ALPHA_CUT_HASH 在 Compatibility 实测不裁剪，阴影整块，先别用
• 硬边抗锯齿：alpha_antialiasing_mode 设 ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE，或开 FXAA、TAA
• 混合透明物不写深度，SSAO 等不作用在它上面
• billboard 加阴影时按场景相机朝向渲染，多相机结果未定义
• 相机绕角色转时影子随相机变形，稳定影子见 references/shadows.md

透明排序

只在 ALPHA_CUT_DISABLED 时调，实测两张重叠精灵，A 在前 0.5 米：

• sorting_offset 在 VisualInstance3D 上，单位米
• render_priority 只在透明物之间生效
• 不靠 no_depth_test 排序，它让精灵穿墙可见

光照

• shaded = true 后接收 Light3D
• billboard 的法线随相机转，光从相机一侧来才亮，背后来为 0
• FIXED_Y 法线水平，正上方的光照不亮，实测俯仰 40 度时亮度 0
• 主光要有水平分量并来自相机一侧，背光面靠环境光补
• 环境光：Environment.ambient_light_source 设成颜色或天空
• 精灵整面一个法线，要法线贴图用 QuadMesh 加 StandardMaterial3D
• billboard_keep_scale 默认 false，QuadMesh billboard 会丢缩放

相机

extends Camera3D

func _ready() -> void:
	projection = Camera3D.PROJECTION_ORTHOGONAL
	size = 360.0 * (1.0 / 32.0)

• 正交 keep_aspect 默认 KEEP_HEIGHT，size 是视口高度对应的米数
• 一贴图像素对一屏幕像素：size = 视口高度像素 × pixel_size，再除以整数倍
• 透视下该关系只在距离 视口高度 × pixel_size ÷ (2 × tan(fov ÷ 2)) 的平面成立
• 正交无近大远小，视差靠相机移动与多层场景
• 透视像素风贴图像素大小随距离变，粗细不均
• 竖直物按 cos 俯仰缩短，地面纵深按 sin 缩短
• 经验起点：俯仰 25 到 45 度，透视 fov 20 到 35 度，非官方数值
• fov 小透视变形小，相机要退得更远
• display/window/stretch/mode 取 canvas_items 时 3D 不受拉伸，UI 按比例缩放
• 取 viewport 时 3D 也低分辨率渲染再放大

像素对齐

• 每个贴图像素占整数个屏幕像素，否则列宽交替不均，实测
• 缩放用整数倍：调相机 size 或视口整数缩放
• 整数倍下相机平移亚像素，列宽不变，实测
• TEXTURE_FILTER_NEAREST 不采样 mipmap，远处颗粒感
• TEXTURE_FILTER_NEAREST_WITH_MIPMAPS 远处平滑，需导入时生成 mipmap
• 透视相机做不到全局整数倍，接受远处不均，或改正交

地面阴影

Decal 只在 Forward+ 与 Mobile 可用，通用写法是平放的 Sprite3D：

extends Sprite3D

func _ready() -> void:
	var gradient := Gradient.new()
	gradient.set_color(0, Color(0.0, 0.0, 0.0, 0.8))
	gradient.set_color(1, Color(0.0, 0.0, 0.0, 0.0))
	var tex := GradientTexture2D.new()
	tex.gradient = gradient
	tex.fill = GradientTexture2D.FILL_RADIAL
	tex.fill_from = Vector2(0.5, 0.5)
	tex.fill_to = Vector2(1.0, 0.5)
	tex.width = 64
	tex.height = 64
	texture = tex
	axis = Vector3.AXIS_Y
	pixel_size = 0.02
	position.y = 0.01

• axis 取 Y 让精灵平放朝上，抬高 0.01 米避免深度闪烁
• 用 Decal 时 cull_mask 排除角色所在层，否则投到角色身上
• 贴花不能改变半透明材质的透明度
• Decal.texture_albedo 不能直接用 ViewportTexture，先 get_image 再建 ImageTexture

SubViewport 与文字

• 2D 场景、2D 骨骼贴进 3D 用 SubViewport 加 ViewportTexture
• SubViewport 不继承项目的默认纹理过滤与像素取整
• 设置、Label3D、世界内 UI、屏幕叠加见 references/subviewport-ui.md
• 雾、景深、移轴见 references/hd2d-environment.md

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法
• references/shadows.md：相机转动时的稳定影子、double_sided 与背光、阴影实测数据
• references/subviewport-ui.md：SubViewport 贴进 3D 的设置、Label3D、世界内 UI、屏幕叠加
• references/hd2d-environment.md：Environment 配方、渲染器支持表、移轴景深
• references/render-check.md：用虚拟显示器读像素验证渲染行为，已验证项清单
• https://docs.godotengine.org/en/stable/tutorials/3d/3d_rendering_limitations.html
• https://docs.godotengine.org/en/stable/tutorials/3d/3d_text.html
• https://docs.godotengine.org/en/stable/tutorials/3d/environment_and_post_processing.html
• https://docs.godotengine.org/en/stable/tutorials/3d/using_decals.html
• https://docs.godotengine.org/en/stable/tutorials/rendering/viewports.html
• https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_images.html