Godot 2D

2D 游戏常见需求的内置节点选择、最短写法和易错点。

范围

先查内置

做法

CharacterBody2D

平台跳跃：

const SPEED := 160.0
const JUMP := -320.0

func _physics_process(delta: float) -> void:
	if not is_on_floor():
		velocity += get_gravity() * delta
	elif Input.is_action_just_pressed("jump"):
		velocity.y = JUMP
	velocity.x = Input.get_axis("left", "right") * SPEED
	move_and_slide()

俯视角：

func _physics_process(_delta: float) -> void:
	velocity = Input.get_vector("left", "right", "up", "down") * 120.0
	move_and_slide()

• velocity 单位像素每秒，move_and_slide 不乘 delta，move_and_collide 要乘
• 默认 grounded 模式按 up_direction 区分地面墙天花板，斜坡加减速

单向平台与推动刚体

• 单向平台：平台的 CollisionShape2D 勾 one_way_collision
• 角色撞上 RigidBody2D 不推动它，每物理帧对它 apply_central_force
• 下穿、漏穿、推箱写法见 references/bodies.md

碰撞层

layer 是我在哪一层，mask 是我扫描哪些层。先在项目设置里给层起名，代码只用 1 到 32 的编号。

[layer_names]

2d_physics/layer_1="world"
2d_physics/layer_2="player"
2d_physics/layer_3="enemy"
2d_physics/layer_4="player_hitbox"
2d_physics/layer_5="enemy_hitbox"

• 检测方 Area2D 只设 mask，除非别的 Area2D 要检测它
• 改单个位：set_collision_layer_value(2, true)，编号从 1 起
• 函数参数里的位掩码是 1 << (层号 - 1)，全部层 0xffffffff
• 敌人互不挤：敌人的 mask 不放 enemy 层

Area2D

signal collected(by: Node2D)

@onready var _shape: CollisionShape2D = $CollisionShape2D

func _ready() -> void:
	body_entered.connect(_on_body_entered)


func _on_body_entered(body: Node2D) -> void:
	collected.emit(body)
	_shape.set_deferred("disabled", true)

• monitoring 是我检测别人，monitorable 是别人能检测我
• 信号回调里禁用形状、改 monitoring 用 set_deferred
• get_overlapping_bodies 每物理步更新一次，刚移动完查不到，优先用信号
• 撞 TileMapLayer 时 body_entered 的参数是 TileMapLayer，不是格子
• 回查格子见 references/tilemaplayer.md

射线与空间查询

[node name="GroundProbe" type="RayCast2D" parent="."]
target_position = Vector2(0, 12)
collision_mask = 1

@onready var _ground: RayCast2D = $GroundProbe

func _physics_process(_delta: float) -> void:
	if _ground.is_colliding():
		var point: Vector2 = _ground.get_collision_point()
		print(point, _ground.get_collider())

const MASK := (1 << 0) | (1 << 2)

func _physics_process(_delta: float) -> void:
	if not Input.is_action_just_pressed("fire"):
		return
	var query := PhysicsRayQueryParameters2D.create(
			global_position, get_global_mouse_position(), MASK, [get_rid()])
	var hit: Dictionary = get_world_2d().direct_space_state.intersect_ray(query)
	if not hit.is_empty():
		var point: Vector2 = hit.position
		print(point, hit.collider)

• RayCast2D.target_position 相对自己
• exclude_parent 默认 true，排除父级碰撞体
• 同一物理步改了位置要读结果，先 force_raycast_update()
• enabled 为 false 时 force_raycast_update() 仍有效
• 查询参数的 mask 默认全部层，节点的 collision_mask 默认只有第 1 层
• intersect_ray 返回字典，没命中为空
• intersect_point intersect_shape 返回字典数组，无 position
• ShapeCast2D、范围与点查询、结果字段见 references/physics-queries.md

TileMapLayer

一层一个节点，多层靠多个节点，旧 TileMap 在编辑器里一键转换。

• 读写用 set_cell、erase_cell、get_cell_tile_data、local_to_map
• 地形接边用 set_cells_terrain_connect，不手写位掩码，挖掉时 terrain 传 -1
• erase_cell 不刷新邻格地形
• 碰撞、导航、遮挡、自定义数据、地形先在 TileSet 建层，再给瓦片填
• 宝箱、火把等带逻辑物件用 Scenes Collection 源，或直接放场景
• 预置格子用无头脚本 set_cell 加 ResourceSaver.save 生成
• 手编 tile_map_data 头 2 字节须为 0，否则整层读成 0 格
• 配置表、peering bit、运行时改瓦片、Y 排序见 references/tilemaplayer.md

Camera2D

[node name="Camera2D" type="Camera2D" parent="Player"]
position_smoothing_enabled = true
position_smoothing_speed = 6.0
limit_left = 0
limit_top = 0
limit_right = 2560
limit_bottom = 720

• 相机做玩家子节点，跟随、边界、平滑、死区都内置
• limit_* 是整数像素
• 震屏改 offset 不改节点位置，噪声用 FastNoiseLite
• offset 在 limit 之后叠加，贴边会露出界外，要夹紧
• 复活、传送后同一段代码里紧接着调 reset_smoothing()
• 不在相机里比较位移距离猜传送，冲刺会误判
• 视差背景用 Parallax2D 4.3+，scroll_scale 小于 1 是远景
• 画面抖、zoom、完整震屏、算 limit、Parallax2D 摆法见 references/camera-parallax.md

绘制顺序

• HUD、暂停菜单、转场放 CanvasLayer，不靠 z_index 堆高
• 同一 layer 值的多个 CanvasLayer 前后顺序不确定
• 跟着世界走带深度感：follow_viewport_enabled 加 follow_viewport_scale

像素风

• 两条路线都把 rendering/textures/canvas_textures/default_texture_filter 设 0 即 Nearest
• 4.7 新建项目默认 canvas_items 加 expand，要手动改
• Sprite2D.centered 默认 true，奇数尺寸贴图落在半像素上变形
• 完整设置、抖动排查、字体、光影分辨率见 references/pixel-art.md

光照、离屏、寻路、自绘

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法
• references/camera-parallax.md：相机边界、平滑死区、完整震屏、Parallax2D 尺寸与摆法
• references/bodies.md：单向平台、下穿、推动刚体、改刚体状态
• references/physics-queries.md：ShapeCast2D、intersect_shape、intersect_point、结果字段
• references/tilemaplayer.md：TileSet 配置表、格子读写、地形、碰撞回查、运行时改瓦片、Y 排序
• references/pixel-art.md：两条像素风路线、抖动排查、导入与字体、光影分辨率
• references/lighting-glow.md：2D 光照与阴影、HDR 2D 与 glow
• references/navigation-culling.md：VisibleOnScreen 系列、NavigationAgent2D 最短用法
• references/drawing.md：Line2D、Polygon2D、_draw 的选择与写法
• https://docs.godotengine.org/en/stable/tutorials/physics/ray-casting.html
• https://docs.godotengine.org/en/stable/tutorials/2d/using_tilemaps.html
• https://docs.godotengine.org/en/stable/tutorials/2d/2d_parallax.html
• https://docs.godotengine.org/en/stable/tutorials/2d/2d_lights_and_shadows.html
• https://docs.godotengine.org/en/stable/tutorials/2d/canvas_layers.html
• https://docs.godotengine.org/en/stable/tutorials/rendering/multiple_resolutions.html
• https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_introduction_2d.html