内容纲要

RuntimePrimitiveDrawing（RuntimeDrawing）节点使用教程

本文档介绍 URuntimeDrawingBlueprintLibrary 中提供的运行时绘制节点（蓝图可调用）的用法、参数含义与常见注意事项。

简体中文 | English

1. 如何在蓝图里找到这些节点

  1. 确保插件/模块已启用并编译通过
  2. 在任意蓝图（Actor / Character / Controller / Widget 等）事件图中：
    • 右键空白处
    • 搜索分类：RuntimeDrawing
    • 节点名以 Draw... 开头（例如 DrawLine、DrawBox、DrawFOVSector 等）

这些函数都带 meta = (WorldContext="WorldContext")
一般在蓝图里会自动从当前蓝图上下文补全，不需要你手动传 World。

2. 通用参数说明（大多数节点都有）

  • WorldLocation / StartLocation / EndLocation：世界坐标（World Space）的点
  • WorldRotation：世界旋转（用于决定朝向，例如盒子、视锥、扇形等）
  • Color (FLinearColor)：线条颜色（线性颜色）
  • Thickness (float)：线条粗细
  • Depth (float)：深度优先级（底层使用 FBatchedLine::DepthPriority / DrawLine 的 DepthPriority）
    • 值越大通常越“靠前”（具体表现与引擎渲染/深度优先级策略有关）
  • Segment / Segments / CircleSegments：分段数（越大越圆滑，但更耗）

3. 各节点用法与参数

3.1 DrawPoint（绘制点）

用途：在世界中绘制一个点。

参数：

  • WorldLocation：点位置
  • Color：颜色
  • Size：点大小（默认 2）
  • Depth：深度优先级（默认 1）

典型用法：

  • 命中点、采样点、路径点可视化

3.2 DrawLine（绘制线段）

用途：绘制一条世界空间线段。

参数：

  • StartLocation / EndLocation：起点/终点
  • Color：颜色
  • Thickness：粗细（默认 2）
  • Depth：深度优先级（默认 1）

3.3 DrawLines（绘制折线）

用途：按顺序连接 Points 数组，绘制折线（Points[i] -> Points[i+1]）。

参数：

  • Points：点数组
  • PointsColor：每个点对应的颜色数组（要求数量与 Points 完全一致，否则函数直接 return）
  • Thickness / Depth：同上

注意：

  • Points.Num() 必须等于 PointsColor.Num()
  • 只会绘制相邻点之间的线，不会自动闭合（闭合请用 DrawPolygon 或自己补最后一个点）

3.4 DrawCircle（绘制圆）

用途：在 XY 平面 上画圆（Z 不变），通过多段折线逼近。

参数：

  • WorldLocation：圆心
  • Radius：半径
  • Segment：分段数（默认 6，太小会很“多边形”）
  • Color / Thickness / Depth

实现特征：

  • 点生成方式：WorldLocation + (cos, sin, 0) * Radius
  • 自动闭合（最后会回到起点）

3.5 DrawSphere（绘制球“线框”）

用途：通过多层圆环绘制“球体线框”效果。

参数：

  • WorldLocation：球心
  • Radius：半径
  • Segment：圆的分段（同时也影响圈数的 clamp）
  • Color / Thickness / Depth

实现特征：

  • 先按 Segment 计算圈数 NumCircles = Clamp(Segment, 4, 64)
  • 在不同 Z 高度绘制多个圆环 + 中间一个大圆

3.6 DrawBox（绘制盒子线框）

用途：绘制旋转盒（OBB）线框。

参数：

  • WorldLocation：盒子中心
  • WorldRotation：盒子旋转
  • BoxExtent：半尺寸（X/Y/Z 方向各一半）
  • Color / Thickness / Depth

实现特征：

  • 通过旋转 8 个角点，然后连线形成边框

3.7 DrawPrisms（绘制棱锥/多棱锥）

用途：从底面多边形的各顶点向顶部连线，形成“棱锥”线框。

参数：

  • WorldLocation：底面中心
  • WorldRotation：整体旋转
  • Radius：底面外接圆半径
  • Height：高度（沿本地 +Z）
  • NumPrisms：底面边数（>=3 才像棱锥）
  • Color / Thickness / Depth

实现特征：

  • 顶点：WorldLocation + Rotate(0,0,Height)
  • 底面：绕圆采样 NumPrisms 个点，并调用 DrawPolygon 画底边
  • 同时每个底点连到顶点

3.8 DrawPolygon（绘制多边形线框）

用途：按 Points 顺序连线并 自动闭合。

参数：

  • Points：多边形顶点（世界坐标）
  • Color / Thickness / Depth

注意：

  • Points 至少要有 1 个点（代码里 <1 会 return）
  • 自动在末尾追加 Points[0] 闭合

3.9 DrawPizza（绘制扇形分片/“披萨”）

用途：从圆心向外画多条半径线，并连接外圈点形成“扇形分割”效果。

参数：

  • WorldLocation：圆心
  • Radius：半径
  • Pieces：分片数（注意实现是 Pieces - 1 条射线）
  • PerPieceDegrees：每片角度（度）
  • Color / Thickness / Depth

注意（实现细节）：

  • 外圈连接使用 DrawLines(Points)，但 没有补回起点，因此外弧不会自动闭合成完整圆。
  • 如你想画完整外圆，请额外调用 DrawCircle。

3.10 DrawSpline（绘制样条线的折线近似）

用途：按指定段数采样 Spline 并用线段连接。

参数：

  • Spline：USplineComponent 引用
  • Color
  • Segment：采样段数（函数里用 float，但循环里当作上限使用）
  • Thickness / Depth

注意（实现细节）：

  • 采样步进：PerSplineSegment = SplinePoints / Segment
  • 循环：for i = 0 .. Segment-2
  • Segment 建议传 >= 2 的整数值（虽然类型是 float）

3.11 DrawArrow（绘制箭头）

用途：画一条主干线 + 4 条箭头翼（在 Right/Up 两个方向各一对）。

参数：

  • StartLocation / EndLocation
  • Color
  • HeadLength：箭头翼长度（会 clamp 到不超过整条箭头长度）
  • HeadAngleDegrees：箭头翼张角（度）
  • Thickness / Depth

注意：

  • Start 与 End 太近（长度接近 0）不会画箭头翼

3.12 DrawFOVSector（绘制 2D 视野扇形）

用途：在 XY 平面基于旋转朝向绘制扇形弧线，并可选绘制两条边界射线/中心线。

参数：

  • WorldLocation：扇形中心
  • WorldRotation：朝向（Forward 为扇形中线方向）
  • Radius：半径
  • AngleDegrees：扇形角度（总角）
  • Segments：弧线分段
  • Color / Thickness / Depth
  • bDrawRays：是否画两条边界射线
  • bDrawArc：是否画外弧
  • bDrawCenterLine：是否画中心线

3.13 DrawFOVBoxFrustum3D（绘制 3D 盒状视锥线框）

用途：按近平面/远平面距离与水平/垂直 FOV 绘制一个相机视锥线框。

参数：

  • WorldLocation：视锥起点（相机位置）
  • WorldRotation：视锥朝向
  • NearDist / FarDist：近平面/远平面距离
  • HorizontalFovDegrees / VerticalFovDegrees：水平/垂直视角（度）
  • Color / Thickness / Depth

实现特征：

  • 自动 clamp：
    • NearDist >= 0
    • FarDist >= NearDist + 0.01
    • FOV 范围 [0.01, 179]
  • 计算近远平面矩形四个角点，并画 12 条边

3.14 DrawLatLongSphere（绘制经纬线球）

用途：用纬线圈 + 经线圈绘制球体网格。

参数：

  • WorldLocation / WorldRotation
  • Radius
  • LatitudeLines：纬线数量（0~64）
  • LongitudeLines：经线数量（3~64）
  • CircleSegments：每个圈的分段（8~256）
  • Color / Thickness / Depth

3.15 DrawHelix（绘制螺旋线）

用途：绘制 3D 螺旋（弹簧状）折线。

参数：

  • WorldLocation / WorldRotation
  • Radius：半径
  • Pitch：每一圈上升的高度（Z 增量）
  • Turns：圈数（>=1）
  • SegmentsPerTurn：每圈分段（4~512）
  • Color / Thickness / Depth

3.16 DrawElectricArc（绘制电弧/闪电）

用途：从 Start 到 End 绘制带随机抖动的折线，可叠加多层形成更“电”的效果。

参数：

  • StartLocation / EndLocation
  • Color
  • Segments：分段数（2~512）
  • JitterAmplitude：抖动幅度（越大越“炸”）
  • Seed：随机种子（相同参数可复现）
  • Thickness / Depth
  • Layers：层数（1~8）
  • LayerAmplitudeMultiplier：每层幅度衰减倍率（例如 0.6）

实现特征：

  • 中间点抖动，端点不抖动
  • 抖动有 sin(t*pi) 衰减（中间最大，两端为 0）
  • 在与主方向垂直的 Right/Up 平面随机偏移

4. 推荐的调用位置（蓝图）

  • 一次性绘制：BeginPlay / 某个事件触发时调用
  • 持续刷新绘制：Tick 中调用（用于实时调试，比如 AI 感知范围、射线命中、路径）
    • Tick 调用可能会有性能开销，建议控制分段数与调用频率

5. 常见问题与排查

  1. 看不到线/点

    • 确认在有 World 的上下文里调用（Actor 蓝图里通常没问题）
    • 尝试增大 Thickness、调整 Color 的 Alpha（确保不透明）
    • 调整 Depth（例如从 0/1 改成更大值）以避免被遮挡（具体与项目渲染设置有关）

  2. DrawLines 没反应

    • 检查 Points.Num() 与 PointsColor.Num() 是否一致（不一致会直接 return）

  3. 圆/球很锯齿

    • 提高 Segment / CircleSegments（代价是更多线段）

6. 节点清单（便于搜索）

  • DrawPoint
  • DrawLine
  • DrawLines
  • DrawCircle
  • DrawSphere
  • DrawBox
  • DrawPrisms
  • DrawPolygon
  • DrawPizza
  • DrawSpline
  • DrawArrow
  • DrawFOVSector
  • DrawFOVBoxFrustum3D
  • DrawLatLongSphere
  • DrawHelix
  • DrawElectricArc

相关推荐

滚动至顶部