• 文档
• 教程
• 游戏开发

CurveXYZTexture 是 Godot 引擎中一种特殊的 1D 纹理：它的红、绿、蓝三个颜色通道分别对应三条单位曲线（Curve资源）上的采样点。本文以 CurveXYZTexture 类参考 为主体，结合 CurveTexture、Curve、ParticleProcessMaterial 与 VisualShaderNodeCurveXYZTexture 等关联文档，系统讲解它的属性语义、与单曲线纹理的取舍、粒子系统与着色器中的实战用法，以及如何用 GDScript 在运行时构建这种纹理。读完你将能够根据场景正确选择并配置曲线纹理，把 3D 轨道速度、逐轴缩放等高频需求落地到 Godot 项目中。

一、类概述：一条纹理、三个通道、三条曲线

从 CurveXYZTexture 类参考 的定义看，CurveXYZTexture 的继承链为：

Texture2D < Texture < Resource < RefCounted < Object

它本质上是 Texture2D 家族的一员，因此可以直接用于材质、粒子系统、着色器采样等所有接受 2D 纹理的场合。

它的核心设计是：纹理的红色通道对应第一条曲线（curve_x）上的点，绿色通道对应第二条（curve_y），蓝色通道对应第三条（curve_z）。这样一张宽度为 W 的 1D 纹理，其第 i 个像素的 RGB 颜色值，就是三条曲线在归一化位置i / (W - 1)处的函数值。

相比分别使用三张独立的 CurveTexture，CurveXYZTexture 进一步简化了"把曲线保存为图像文件"这一任务——把纹理导出/保存为图片时，一张图即可同时承载三条曲线。文档中还特别给出了选择建议：

• 如果只需要在单张纹理里存储一条曲线，应优先使用 CurveTexture；
• 如果需要在单张纹理里存储最多三条曲线，则使用 CurveXYZTexture；
• 渐变类需求可参考 GradientTexture1D 与 GradientTexture2D。

二、属性详解

CurveXYZTexture 的公开属性在 类参考的属性表 中列出，除继承自 Resource 的resource_local_to_scene（默认false）外，共 4 个核心属性：

2.1 curve_x / curve_y / curve_z

三个属性的语义完全对称，分别把对应曲线采样到 R、G、B 通道上。类参考原文强调：这些曲线应该是单位曲线（unit Curve）。所谓单位曲线，按 Curve 类参考 的定义，是指定义域（X 轴）落在0到1之间的曲线。Godot 中许多资源与节点都假定输入的是单位曲线，例如CPUParticles2D.angle_curve、Line2D.width_curve等。

三个属性各带一对 setter/getter：

• set_curve_x(value: Curve)/get_curve_x()
• set_curve_y(value: Curve)/get_curve_y()
• set_curve_z(value: Curve)/get_curve_z()

2.2 width

width（默认256）决定纹理的宽度（像素），即曲线被离散采样生成多少个 texel。类参考原文指出其取舍关系：

更高的值能更好地表示高频数据（例如突然的方向变化），但代价是更长的生成时间和更高的内存占用。

实践上：曲线平缓、低频变化（如渐变式的加速/衰减）用默认 256 足够；若曲线包含陡峭拐点、阶跃式的方向突变，可适当提高到 512 甚至 1024；若场景中实例化大量此类纹理，则应在保证采样精度的前提下尽量降低 width 以控制显存与生成开销。

2.3 属性修改的即时性

从引擎的资源刷新机制（Curve 拥有domain_changed、range_changed信号，见 Curve 类参考）可以推断：编辑 Curve 后纹理会随之重新生成，曲线与纹理之间保持数据同步，因此既可以在编辑器中可视化编辑曲线并即时预览，也可以在运行时通过脚本修改曲线数据来驱动纹理内容更新。

三、与 CurveTexture 的对比与选型

CurveTexture 是"像素亮度对应一条曲线上点"的 1D 纹理。两者的关键差异如下：

CurveTexture 的TEXTURE_MODE_RGB常量说明提到"在 RGB 三通道均匀存储曲线会占用更多显存，但对只读取 G/B 值的着色器更兼容"；反过来，CurveXYZTexture 则天生把 R、G、B 三个通道分别留给三条不同的曲线，两者使用意图完全不同。当一条曲线足够时，用 CurveTexture 节省显存；当需要三条独立曲线且希望打包进同一张纹理时，用 CurveXYZTexture。

四、实战：在粒子系统中使用 CurveXYZTexture

CurveXYZTexture 最典型的应用场景在粒子系统，证据集中在 ParticleProcessMaterial 类参考：

1. 3D 轨道速度（orbital velocity）：ParticleProcessMaterial的轨道速度参数配合set_param_texture()使用时可传入曲线纹理，类参考原文明确注释："对于 3D 轨道速度，请使用 CurveXYZTexture"。因为三维轨道速度本身是向量，用 R/G/B 三通道分别驱动 X/Y/Z 三个方向的轨道分量，正是这条纹理的设计初衷。

2. 逐轴缩放（per-axis scale）：scale_curve属性接受 Texture2D，文档原文为："每个粒子的缩放会沿此 CurveTexture 随生命周期变化；如果改供 CurveXYZTexture，则缩放会按轴分离"——即三条曲线分别控制粒子 X、Y、Z（或 2D 的 X/Y）轴上的缩放，实现"压扁-拉长"式的非均匀缩放动画，这是单通道 CurveTexture 做不到的。

3. 速度缩放曲线（scale over velocity）：scale_over_velocity_curve同样接受 CurveTexture 或 CurveXYZTexture，用于"根据粒子速度进行缩放"。

因此，在 GPUParticles2D、GPUParticles3D 的process_material上，CurveXYZTexture 是把三维曲线数据送入 GPU 粒子系统的标准通道。

五、实战：在可视化着色器中直接编辑与采样

VisualShaderNodeCurveXYZTexture 是可视化着色器（VisualShader）中执行 CurveXYZTexture 查的节点，其继承链为：

VisualShaderNodeResizableBase < VisualShaderNode < Resource < RefCounted < Object

它的核心价值在于类参考中强调的一点：自带纹理曲线的内置编辑器——在可视化着色器图内选中该节点，即可直接在编辑器中拖拽编辑三条曲线，无需在外部资源面板单独维护三条 Curve。节点仅有一个属性texture（set_texture()/get_texture()），用于绑定作为采样来源的 CurveXYZTexture。

在可视化着色器中，该节点输出的颜色向量即为三条曲线在当前 UV 坐标下的采样值（R 通道取 curve_x、G 通道取 curve_y、B 通道取 curve_z），可直接接入后续数学节点参与计算。

六、GDScript 运行时构建与着色器采样

6.1 用 GDScript 创建并填充 CurveXYZTexture

在编辑器外部（或运行时动态生成）构建一张 CurveXYZTexture 非常简单：

# 创建三条单位曲线（定义域 X 轴保持在 0..1） var curve_x := Curve.new() curve_x.add_point(Vector2(0.0, 0.0)) curve_x.add_point(Vector2(0.5, 0.8)) curve_x.add_point(Vector2(1.0, 1.0)) var curve_y := Curve.new() curve_y.add_point(Vector2(0.0, 1.0)) curve_y.add_point(Vector2(1.0, 0.0)) var curve_z := Curve.new() curve_z.add_point(Vector2(0.0, 0.0)) curve_z.add_point(Vector2(1.0, 1.0)) var tex := CurveXYZTexture.new() tex.curve_x = curve_x # 写入红色通道 tex.curve_y = curve_y # 写入绿色通道 tex.curve_z = curve_z # 写入蓝色通道 tex.width = 512 # 提高分辨率以表现高频拐点

其中Curve.add_point()的完整签名（见 Curve 方法表）为：

add_point(position: Vector2, left_tangent: float = 0, right_tangent: float = 0, left_mode: TangentMode = TANGENT_FREE, right_mode: TangentMode = TANGENT_FREE) -> int

若曲线由第三方工具（如粒子系统）消费，建议保持单位曲线约束；曲线编辑完成后可通过bake()或依赖sample_baked()时自动烘焙的机制获得稳定的采样缓存。

6.2 把 CurveXYZTexture 接入粒子系统

var material := ParticleProcessMaterial.new() # 3D 轨道速度：把曲线纹理交给轨道速度参数 material.set_param_texture(ParticleProcessMaterial.PARAM_ORBIT_VELOCITY, tex) # 或用于逐轴缩放 material.scale_curve = tex

随后把该材质赋给GPUParticles3D.process_material即可。

6.3 在自定义着色器中采样

CurveXYZTexture 是 Texture2D，在着色器中可用标准的texture()函数按 UV 的 u 坐标采样，R/G/B 通道分别对应三条曲线：

shader_type canvas_item; uniform sampler2D curve_xyz : repeat_disable; void fragment() { float value_x = texture(curve_xyz, vec2(UV.x, 0.0)).r; float value_y = texture(curve_xyz, vec2(UV.x, 0.0)).g; float value_z = texture(curve_xyz, vec2(UV.x, 0.0)).b; // 用三个采样值驱动三维计算，例如方向、颜色或位移 }

由于曲线被离散化到width个像素，采样结果的精度上限由width决定，这也是理解"width 越高越能表现突然方向变化"的根源：离散像素数越密，陡峭拐点越不容易被欠采样抹平。

七、使用建议与注意事项

综合 CurveXYZTexture 类参考 及上述关联文档，给出以下工程建议：

1. 保持单位曲线：三个通道的 Curve 都应保持定义域在0..1之间，这是粒子系统等下游组件的前提假设；
2. 按需选择纹理类型：单条曲线用 CurveTexture（可配合TEXTURE_MODE_RED省显存），两到三条曲线用 CurveXYZTexture；
3. width 是精度-开销的平衡旋钮：默认 256 像素满足绝大多数场景；存在高频突变时提高分辨率，批量实例化时谨慎放大；
4. 可视化着色器优先用专用节点：VisualShaderNodeCurveXYZTexture 内置曲线编辑器，编辑体验优于外部资源拼装；
5. 运行时修改曲线即可驱动纹理更新：Curve 的domain_changed/range_changed信号（见 Curve 类参考）保证曲线数据变更会传导到依赖方，可在运行时动态改曲线实现"活的"纹理数据。

把握住"一条纹理 = RGB 三通道 = 三条单位曲线"这一核心心智模型，CurveXYZTexture 就能在粒子系统、可视化着色器与自定义着色器中发挥出把三维曲线数据高效送入 GPU 的价值。

• 文档
• 教程
• 游戏开发