Voxel Plugin

Voxel Plugin 2 是适用于 Unreal Engine 的程序化地形系统。您用图和形状来描述地面。它会在编辑器中实时构建地形，带有洞穴、悬挑和浮空岩石，这些是基于 heightmap 的 Landscape 做不到的。

借助 Voxel Plugin 扩展，Ultimate Engine CoPilot 可以为您构建这些设置。您可以要求起伏的丘陵、更高的山脉、一个洞穴或一座浮空岛。

AI 会创建 Voxel World、图和 Stamp。它会涂刷表面、散布树木并检查结果。

它已使用 Voxel Plugin 2.0p8 在 Unreal Engine 5.6 和 5.7 上测试过。本页的地形图片来自 5.7。

---

这里的“voxel”是什么意思

“Voxel”指的是 Voxel Plugin 存储地形的方式，而不是它的外观。默认情况下地形是平滑的。插件保存一个密度值网格，并穿过它绘出一个平滑的表面。

如果您期待的是 Minecraft 那样的方块，这是一个可以要求的设置。请参阅 方块地形。

AI 给出的每个回答里都会出现四个词：

• Voxel World。 绘制地形的 Actor。每个关卡一个，它自己不会产生地形。
• Stamp。 World 绘制的指令，作为 Actor 放置在关卡中。一个 Stamp 的意思是“把这个加在这里”：一张图、一个球体、一张 heightmap、一个 mesh 或一条 spline。
• 图。 生成地形的节点网络，例如把噪声送入 Output Height 节点。许多 Stamp 可以运行同一张图。
• Layer 与 layer stack。 它们决定什么写在哪里以及按什么顺序，所以您可以分多个阶段构建一个世界。

一个 height Stamp 为每个位置给出一个高度：速度快，没有悬挑。一个 volume Stamp 是一个 3D 形状：洞穴、拱门和浮空岩石。

---

您需要什么

• Voxel Plugin 2，已在您的项目中安装并启用。
• 开启了 Voxel Plugin 扩展的 Ultimate Engine CoPilot。
• 一个带有天空和光照的关卡。新关卡两者都没有，所以在它们存在之前地形会渲染成黑色。只需在同一条提示里要求“天空、太阳和雾”即可。

没有 Voxel Plugin 时，该扩展不会造成任何影响。每个 Voxel 工具都会返回一条消息，说明需要安装什么。

有一个设置步骤属于 Voxel，而不是我们。 Voxel 会向引擎添加一个小的着色器钩子（shader hook），让涂刷的表面能够渲染它们的材质。在它被应用之前，地形显示的是 Voxel 的默认网格，而不是您的材质。

请使用 Voxel 自己的工具来应用它，并按照 Voxel 的设置指南 操作。它会编辑引擎的着色器文件，所以使用该引擎的每个项目在下次打开时都会重新编译着色器。

让 AI “检查 Voxel 状态”，它会告诉您钩子是否已应用。

---

开启扩展

1. 搜索。 打开 设置 > 扩展，搜索“voxel”。
2. LOADED。 扩展运行后，卡片上会显示 LOADED。
3. 开关。 把它打开。它默认是关闭的。

然后让 AI “检查 Voxel 状态”。它会报告是否找到了 Voxel Plugin、关卡中有什么，以及着色器钩子是否已应用。

---

用一条提示构建地形

请描述外观，而不是设置。这条提示生成了下一张图片中的地形：

Create a Voxel terrain with rolling hills and make it look good with a sky,
sun and fog. Put everything in /Game/VoxelDemo.

AI 创建了一个 Voxel World、一张用于丘陵的 height 图、一个使用它的 Stamp、一个草地表面，以及天空、太阳、云和雾。结果如下：

1. 地形，在视口中实时渲染。
2. 总结。 它说明构建了什么、测量了什么，以及添加了哪些您没有要求的东西。这里是云和一种草地材质，因为没有材质时，地形会渲染 Voxel 的默认网格。
3. 资产，保存在您指定的文件夹中：图、草地材质和关卡。

---

改变形状

用平常的话提出修改。

Make the hills taller and more rugged, with fine detail on the peaks.

AI 会编辑 height 图。这次运行中，它修改了基础噪声，增加了 octave，并添加了第二个只作用于山峰的噪声。视口使用同一台摄像机，修改前在左，修改后在右：

这张图是一张普通的 Voxel 图。从 Content Browser 打开它，就可以查看或修改 AI 构建的内容。

1. Advanced Noise 2D。 生成丘陵的噪声，带有它的振幅、特征尺度和 octave。
2. Output Height。 地形读取的节点。高度范围可避免高耸的山峰被截断。
3. Make Box 2D From Radius。 这张图所覆盖的区域。

若要按 Stamp 调整一张图，请要求添加参数：“添加高度和特征大小的参数，这样我就可以调整每个 Stamp。”

这样同一张图可以在一处生成平缓的草甸，在另一处生成高耸的山峰。没有值的参数为 0，所以 AI 总会给每个参数一个起始值。

---

涂刷、散布与挖凿

涂刷和散布是让地形看起来像一个真实地方的步骤。

Paint the terrain with the textured materials from the Voxel examples: cliff
rock on the steep slopes and muddy leaves on the flatter ground.

Scatter trees across the hills, thicker on the flatter ground, using the three
sample trees from the PCG plugin.

AI 通过图来涂刷，所以岩石落在陡坡上，落叶落在平地上。树木来自一张把 mesh 放到地形表面的散布图。

它检查涂刷的方式是在若干点对地形采样并读回那里是哪种表面，而不只是用眼睛看。

volume Stamp 负责 height Stamp 做不到的部分。

Add a floating rock island above the valley.

Carve a cave into the tallest mountain.

岛屿是一个把岩石 mesh 当作地形的 Stamp。

洞穴由相互重叠、从山体中减去的球体 Stamp 构成：一个洞口、若干隧道和一个洞室。它的洞壁光滑，在球体相交处略有波浪状的起伏。

---

方块地形

要求“把这个地形做成方块的”，同样的 Stamp 就会被渲染成阶梯状的立方体。左边是平滑地形，右边是修改后的同一台摄像机：

AI 会做三件事。它创建一个 blockiness 值，让 World 指向它，并把该值设置到每个应当呈方块状的 Stamp 上。仅靠前两步什么也不会改变。

值为 1 是完整的方块，0 是平滑，介于两者之间的值会部分吸附。一个方块宽一个体素，在默认体素大小下为 1 m。

方块的面仍然是平滑着色的。要得到硬边的面，需要在材质中使用 flat normal，这需要您自己在材质中设置。

---

您可以提出的请求

• “创建一个带有起伏丘陵以及天空、太阳和雾的 Voxel 地形。”
• “让丘陵更高、更崎岖。”
• “在东边为山脉添加第二个 Stamp，带有它自己的高度。”
• “沿这些点添加一条河流”（spline Stamp 会跟随您给出的点）。
• “把这张 heightmap 纹理用作地形。”
• “把这个岩石 mesh 用作 Stamp。”
• “在平地上放草，在陡坡上放岩石。”
• “在丘陵上散布树木。”
• “把这些树和岩石放到地面上。” 编辑器中没有体素地形的碰撞，所以普通的 line trace 会落空。AI 会向地形本身询问地面在哪里。
• “为什么什么都没有渲染？” AI 会读取 Voxel 的日志，因为 Voxel 把许多图和 Stamp 的错误只报告在那里。

在这些请求背后，该扩展有 23 个工具：

• 状态与资产。 检查 Voxel、列出资产，创建和编辑图、layer、layer stack、mega material、surface type、heightmap 和 mesh 资产。
• World。 创建它、读取它并更改它的设置，包括导航和碰撞。
• Stamp。 列出 Stamp 类型，然后添加、读取和更改各种 Stamp。
• 图。 列出节点类型、读取一张图，然后添加、连接、设置和移除节点，并添加参数。
• Actor。 添加、读取和更改 scatter 与 sculpt Actor。
• 地面查询。 读取各点的高度、坡度和表面，并把 Actor 放到地形上。
• 消息。 读取 Voxel 记录的内容。

---

技巧

• 描述外观并指定文件夹。 “把所有内容放在 /Game/VoxelDemo 中”可以让图、材质和表面保持在一起。
• 每条消息一步。 先地形，再形状，再涂刷，最后树木。每个结果都看得见，并且您可以单独撤销最后一步。
• 在第一条提示里就要求天空和光照。 没有它们，地形会渲染成黑色。
• 使用示例表面。 Voxel 自带的示例内容里有现成的带纹理材质。像上面那样在提示中点出它们的名字。
• 保存关卡。 AI 会保存它创建的图和材质，但 Stamp 存在于关卡中，所以请让它保存关卡，或在关闭前按 Ctrl+S。
• 阅读总结中的“需要了解的事项”部分。 AI 会列出它在视口中看不到的内容，例如岛屿在画面之外。

---

局限

• 交互式雕刻（sculpting）和保存的 sculpt 数据不在涵盖范围内。
• Voxel 的 PCG 节点可以添加和连接，但尚未针对 Voxel World 运行过完整的 PCG。
• 运行时编辑和多人游戏不在涵盖范围内。
• 超出 World 自身设置的 navmesh 和 collision invoker 不在涵盖范围内。
• Voxel 的材质编辑器和函数库图不在涵盖范围内。对这些请使用通用的属性工具。
• 带有涂刷表面的地形需要 Voxel 的着色器钩子，并且 Voxel 图只能用 Voxel 提供的节点类型构建，AI 会为您查找这些类型。
• AI 从不把 Voxel 链接进您的项目。如果 Voxel 在更新中重命名了某个东西，工具会指出缺失的字段，而不是猜测。

权限

读取不受限制：检查状态、读取一张图或对地形采样时从不询问。更改遵循您的 Ask Before Edit 或 Auto Edit 设置，与其他所有工具一样。

---

它如何运作

• 插件之间没有链接。 该扩展仅通过反射访问 Voxel Plugin，因此无论是否安装了 Voxel，Ultimate Engine CoPilot 的构建和运行方式都相同，并且该扩展可以在设计相同的各个 Voxel 版本之间继续工作。
• 处处可用。 这些工具可以在 CoPilot 的聊天中、在 Claude Code 和 Cursor 等外部 MCP 客户端中，以及在编码代理中使用。请参阅 MCP 集成。
• 更改实时显示。 AI 编辑时 Voxel 会更新地形，图会在 Voxel 自己的编辑器中打开。

关于扩展的工作方式，请参阅 扩展；关于 AI 如何检查正在运行的游戏，请参阅 游戏测试。