最后同步日期：2026-04-15 | Godot 官方原文 — Line2D

Line2D

节点继承关系

继承链：Node → Node2D → CanvasItem → Line2D

定义

Line2D 绘制一条 2D 折线——你给它一组点，它就把这些点用线段连起来。它可以设置线宽、颜色、渐变粗细等效果，非常适合做拖尾特效、激光、路径可视化等视觉效果。

一句话理解：Line2D 就像一支画笔，你告诉它经过哪些点，它就按顺序把这些点连成一条线。

使用频率：★★★ 一般常用——视觉特效和调试工具中常用。

节点用途

• 绘制拖尾效果（角色移动轨迹、武器挥舞路径）
• 绘制激光/光束效果
• 路径可视化（AI 寻路路径调试）
• 绘制折线图表、波形图
• 雷达扫描线效果

使用场景

场景	说明
角色拖尾	角色移动时留下渐隐的轨迹
激光/光束	武器发射的激光效果
AI 路径调试	可视化 AI 的寻路路径
波形显示	音频波形、心电图等
绳索/链条	物理模拟的绳索视觉效果

常用节点搭配

搭配节点	搭配方式	用途
Path2D	配合使用	Path2D 定义路径，Line2D 可视化显示
Polygon2D	配合使用	Line2D 画边框，Polygon2D 填充内部
Timer	作为兄弟子节点	定时更新点实现动态效果

生效必备素材/资源

资源类型	格式	说明
Texture2D（可选）	.png、.webp	线条纹理。不设置则使用纯色

节点属性与信号

线条属性

属性	类型	默认值	继承自	说明
Points	PackedVector2Array	[]	—	线条经过的点数组
Width	float	10.0	—	线条宽度
DefaultColor	Color	Color(1, 1, 1, 1)	—	线条默认颜色

渐变效果

属性	类型	默认值	继承自	说明
Gradient	Gradient	null	—	沿线条的颜色渐变
WidthCurve	Curve	null	—	线宽变化曲线（可做出渐变粗细效果，如拖尾）
TextureMode	LineTextureMode	Stretched	—	纹理模式：拉伸/瓦片
Texture	Texture2D	null	—	线条纹理
JointMode	LineJointMode	Sharp	—	连接点样式：尖锐/斜接/圆形
BeginCapMode	LineCapMode	None	—	起始端样式
EndCapMode	LineCapMode	None	—	结束端样式：无/箱子/圆形
RoundPrecision	int	8	—	圆角精度

继承自 CanvasItem 的常用属性

属性	类型	默认值	继承自	说明
SelfModulate	Color	Color(1, 1, 1, 1)	CanvasItem	颜色调制
Visible	bool	true	CanvasItem	是否可见
ZIndex	int	0	CanvasItem	绘制顺序

信号

Line2D 本身没有自定义信号，继承自 CanvasItem。

常用方法

方法	返回值	说明
AddPoint(position, index)	void	添加一个点
RemovePoint(index)	void	移除指定索引的点
ClearPoints()	void	清除所有点
GetPointCount()	int	获取点的数量
GetPointPosition(index)	Vector2	获取指定索引的点位置
SetPointPosition(index, position)	void	设置指定索引的点位置

代码示例

基础用法：画一条折线

C

var line = new Line2D();
line.DefaultColor = Colors.Yellow;
line.Width = 3;
line.JointMode = Line2D.LineJointMode.Round;  // 圆角连接
line.EndCapMode = Line2D.LineCapMode.Round;    // 圆形端点

line.AddPoint(new Vector2(0, 0));
line.AddPoint(new Vector2(100, 50));
line.AddPoint(new Vector2(200, 0));
line.AddPoint(new Vector2(300, 80));
AddChild(line);

GDScript

var line = Line2D.new()
line.default_color = Color.YELLOW
line.width = 3
line.joint_mode = Line2D.LINE_JOINT_ROUND  # 圆角连接
line.end_cap_mode = Line2D.LINE_CAP_ROUND    # 圆形端点

line.add_point(Vector2(0, 0))
line.add_point(Vector2(100, 50))
line.add_point(Vector2(200, 0))
line.add_point(Vector2(300, 80))
add_child(line)

拖尾效果（角色移动轨迹）

C

public partial class TrailEffect : Line2D
{
    [Export] public float ExTrailLength = 50f;
    [Export] public int ExMaxPoints = 30;

    public override void _Ready()
    {
        Width = 3;
        DefaultColor = Colors.Cyan;

        // 设置渐变粗细：越老越细
        var widthCurve = new Curve();
        widthCurve.AddPoint(0, 0);       // 起点（最老）：粗细为 0
        widthCurve.AddPoint(1, 3);       // 终点（最新）：粗细为 3
        WidthCurve = widthCurve;
    }

    public override void _Process(double delta)
    {
        // 在脚本挂载的父节点位置添加点
        var parent = GetParent<Node2D>();
        if (parent != null)
        {
            AddPoint(parent.Position);
        }

        // 限制最大点数
        while (GetPointCount() > ExMaxPoints)
        {
            RemovePoint(0);
        }
    }
}

GDScript

extends Line2D

@export var trail_length: float = 50.0
@export var max_points: int = 30

func _ready():
    width = 3
    default_color = Color.CYAN

    # 设置渐变粗细：越老越细
    var width_curve = Curve.new()
    width_curve.add_point(Vector2(0, 0))    # 起点（最老）：粗细为 0
    width_curve.add_point(Vector2(1, 3))    # 终点（最新）：粗细为 3
    width_curve = width_curve

func _process(delta):
    # 在脚本挂载的父节点位置添加点
    var parent = get_parent() as Node2D
    if parent:
        add_point(parent.position)

    # 限制最大点数
    while get_point_count() > max_points:
        remove_point(0)

激光效果（动态绘制）

C

public partial class LaserBeam : Line2D
{
    [Export] public float ExMaxDistance = 500f;
    [Export] public Color ExLaserColor = new Color(1, 0, 0, 0.8f);

    private RayCast2D _rayCast;

    public override void _Ready()
    {
        _rayCast = GetParent<RayCast2D>();
        DefaultColor = ExLaserColor;
        Width = 4;
        EndCapMode = Line2D.LineCapMode.Round;
    }

    public override void _Process(double delta)
    {
        ClearPoints();

        // 从射线投射获取终点
        _rayCast.ForceRaycastUpdate();

        Vector2 endPos;
        if (_rayCast.IsColliding())
        {
            endPos = _rayCast.GetCollisionPoint();
        }
        else
        {
            endPos = _rayCast.TargetPosition;
        }

        AddPoint(Vector2.Zero);
        AddPoint(endPos - _rayCast.GlobalPosition);
    }
}

GDScript

extends Line2D

@export var max_distance: float = 500.0
@export var laser_color: Color = Color(1, 0, 0, 0.8)

@onready var _ray_cast: RayCast2D = get_parent()

func _ready():
    default_color = laser_color
    width = 4
    end_cap_mode = Line2D.LINE_CAP_ROUND

func _process(delta):
    clear_points()

    # 从射线投射获取终点
    _ray_cast.force_raycast_update()

    var end_pos: Vector2
    if _ray_cast.is_colliding():
        end_pos = _ray_cast.get_collision_point()
    else:
        end_pos = _ray_cast.target_position

    add_point(Vector2.ZERO)
    add_point(end_pos - _ray_cast.global_position)