2d-essentials

Godot 4.3+ 中的 2D 基础

所有示例均面向 Godot 4.3+，不使用已弃用的 API。先展示 GDScript，再展示 C#。

相关技能： player-controller，用于 CharacterBody2D 移动模式；animation-system，用于 AnimatedSprite2D 和精灵动画；physics-system，用于碰撞形状和射线检测；camera-system，用于 Camera2D 跟随和震动；shader-basics，用于 2D 着色器和后期处理；godot-optimization，用于渲染和绘制调用优化。

---

1. 画布层与绘制顺序

绘制顺序规则

在同一个画布层中，节点按照场景树顺序绘制——在场景面板中位置更靠下的节点会绘制在上层。使用 z_index 可覆盖此顺序，而无需调整场景树。

# Draw this node above siblings (default z_index is 0)
z_index = 10

# z_index is relative to the parent by default (z_as_relative = true);
# set it false to make this node's z_index absolute
z_as_relative = false

CanvasLayer

CanvasLayer 会创建一个独立的渲染层，拥有自己的变换，不受摄像机影响。layer 值越大，绘制位置越靠上。

层级	典型用途
-1	视差背景
0	默认游戏层（所有未使用 CanvasLayer 的 Node2D）
1	HUD / UI 覆盖层
2	暂停菜单、屏幕转场

# Scene tree example
Main
├── ParallaxBackground (CanvasLayer, layer = -1)
│   └── Parallax2D (follow_viewport = false — the layer doesn't follow the camera)
├── World (Node2D — default layer 0)
│   ├── TileMapLayer
│   └── Player
└── HUD (CanvasLayer, layer = 1)
    └── Control

注意： 控制绘制顺序不一定要使用 CanvasLayer。对于同一个游戏世界中的对象，请使用 z_index 或场景树顺序。CanvasLayer 用于不受摄像机影响的元素（HUD、视差、转场）。

画布变换

Camera2D 通过修改视口的 canvas_transform 运作。如需手动控制：

# Scroll the canvas directly (equivalent to camera movement)
get_viewport().canvas_transform = Transform2D(0, Vector2(-200, 0))

坐标转换

# Local to canvas (world) coordinates
var world_pos: Vector2 = get_global_transform() * local_pos
var local_pos: Vector2 = get_global_transform().affine_inverse() * world_pos

# Local to screen coordinates (accounts for camera, stretch, window)
var screen_pos: Vector2 = get_viewport().get_screen_transform() * get_global_transform_with_canvas() * local_pos

// Local to canvas (world) coordinates
Vector2 worldPos = GetGlobalTransform() * localPos;
Vector2 localFromWorld = GetGlobalTransform().AffineInverse() * worldPos;

// Local to screen coordinates
Vector2 screenPos = GetViewport().GetScreenTransform() * GetGlobalTransformWithCanvas() * localPos;

---

2. TileMap 系统

TileMapLayer（Godot 4.3+）是较新的 API——一个 TileMap 就是一个节点、一个图层。使用 TileSet 资源（图集 + 属性 + 物理 + 自定义数据）来控制绘制。使用地形自动平铺，根据生物群系选择合适的图块；使用场景集合图块，在图块上放置场景实例。

关于完整的 TileSet 设置、图集 / 物理 / 地形配置、图块自定义数据、场景集合图块，以及 4.5+ 图块碰撞凸起自动合并修复，请参阅 references/tilemap.md。

---

3. 视差滚动

Parallax2D（Godot 4.3+）取代了较旧的 ParallaxBackground/ParallaxLayer 组合。为每个图层设置 scroll_scale（0 = 静止，1 = 以 1:1 比例跟随摄像机，小于 1 的值用于表现深度）。添加 repeat_size 以实现无限平铺。

关于 Parallax2D 设置、横向卷轴图层示例、无限重复、分屏视差和常见错误，请参阅 references/parallax.md。

---

4. 2D 灯光与阴影

PointLight2D 和 DirectionalLight2D 可在精灵上投射光照——搭配法线贴图可实现 3D 风格的着色，也可对平面精灵使用加法混合照明。使用 LightOccluder2D 投射阴影。

关于节点概览、PointLight2D 属性、阴影设置、剔除遮罩、遮挡物、2D 法线贴图、像素艺术照明技巧，以及使用加法精灵伪造灯光的技巧，请参阅 references/lights-and-shadows.md。

---

5. 2D 粒子系统

粒子数量较多（≥ 50 个，由 GPU 驱动）时使用 GPUParticles2D；粒子数量较少或平台不支持 GPU 时使用 CPUParticles2D。GPUParticles2D 由 ParticleProcessMaterial 驱动；CPUParticles2D 则将相同参数作为自身属性提供。

关于 GPU 与 CPU 的选择依据、基本设置、ParticleProcessMaterial 的 2D 属性、从纹理发射、翻页动画、可见区域，以及常见的 2D 配置示例，请参阅 references/2d-particles.md。

---

6. 自定义绘制

在任何 CanvasItem 上重写 _draw()，即可绘制线条、多边形、文本或任意形状。调用 queue_redraw() 触发重新渲染（切勿直接调用 _draw()）。

关于 _draw() 方法、重绘模式、完整的绘制方法参考、默认字体用法、@tool 编辑器预览和线宽注意事项，请参阅 references/custom-drawing.md。

Godot 4.7+： DrawableTexture2D — 一种可在运行时绘制的纹理类型 — 已在 4.7 中以实验性功能发布，目前尚不建议用于生产环境。

---

7. 2D 网格

何时使用

当大型透明区域浪费 GPU 填充率时，MeshInstance2D 可替代 Sprite2D。GPU 会绘制整个纹理四边形，包括完全透明的像素；网格可以消除这些开销。

将 Sprite2D 转换为 MeshInstance2D

1. 选择 Sprite2D
2. 菜单：Sprite2D → Convert to MeshInstance2D
3. 调整扩展和简化参数
4. 点击“Convert 2D Mesh”

最适合的对象：

• 带透明区域、屏幕大小的图像
• 形状不规则的视差层
• 带大块透明边框的分层图像
• 移动设备／低端 GPU 目标平台

---

8. 2D 抗锯齿

按节点设置抗锯齿（推荐）

许多绘制方法都支持 antialiased 参数：

draw_line(Vector2.ZERO, Vector2(100, 50), Color.WHITE, 2.0, true)  # antialiased = true

// Equivalent in a CanvasItem subclass (e.g., a custom Control or Node2D):
public override void _Draw()
{
    DrawLine(new Vector2(0, 0), new Vector2(100, 50), Colors.White, width: 2.0f, antialiased: true);
}

Line2D 有一个 antialiased 属性（C#：Antialiased），但 Line2D 只存储该属性，不会将其传递给绘制调用，因此不会产生可见效果；若要让 Line2D 边缘平滑，请使用 MSAA 2D（下文）或边缘柔和的纹理。

⚠️ Godot 4.7 中的变更： CanvasItem 的抗锯齿线条绘制不再添加抗锯齿羽化效果。羽化会让 draw_line() 样式的线条看起来比预期更粗，因此升级后，抗锯齿线条会变细；依赖旧有外观的项目必须绘制更粗的 width。请参阅 4.7 迁移指南。

MSAA 2D

仅适用于 Forward+ 和 Mobile 渲染器（不适用于 Compatibility）。

Project Settings → Rendering → Anti Aliasing → Quality → MSAA 2D

级别：2x、4x、8x。

MSAA 会影响	MSAA 不会影响
几何图形边缘（线条、多边形）	最近邻纹理内部的锯齿
接触纹理边缘的精灵边缘	自定义 2D 着色器输出
	字体渲染
	使用 Light2D 时的镜面反射锯齿

对于像素艺术： 不要启用 MSAA 2D，它会模糊刻意保持锐利的边缘。请有选择地使用按节点设置的 antialiased 参数。

---

9. 2D 吸附与像素级精准

编辑器吸附

2D 工具栏中的三点菜单：

• Grid Step — 吸附到网格（配置 Grid Offset 和 Step）
• Rotation Step — 按角度吸附旋转
• Smart Snap — 吸附到父节点、节点锚点、边、中心和参考线

运行时像素吸附

对于像素艺术游戏，启用像素吸附以防止亚像素抖动：

• 节点： Project Settings → Rendering → 2D → Snapping → Snap 2D Transforms to Pixel
• 顶点： Project Settings → Rendering → 2D → Snapping → Snap 2D Vertices to Pixel
• 控件： Project Settings → GUI → General → Snap Controls to Pixels

---

10. 实现检查清单

• 背景是 Sprite2D 或 ColorRect（而非默认的清屏颜色），以便接收 2D 光照
• TileSet 保存为外部 .tres 资源，以便在多个关卡中复用
• TileSet 已启用 Use Texture Padding，以防纹理渗色
• Parallax2D 纹理的左上角位于 (0,0)，而非居中
• repeat_size 与实际纹理尺寸一致
• 如果摄像机可能缩小视图，则增大 repeat_times
• 启用阴影时，为投射阴影的对象添加 LightOccluder2D 节点
• 配置 Light 和遮挡物的剔除遮罩，以避免不必要的光照计算
• GPUParticles2D 具有有效的可见区域矩形（通过 Particles 菜单自动生成）
• 自定义绘制状态发生变化时，调用 queue_redraw()
• 瓦片上的碰撞形状使用 Physics Layer 系统，而非手动添加 CollisionShape2D 节点
• 在移动设备／低端设备目标上，将大型透明精灵转换为 MeshInstance2D