Godot六边形地块程序化生成实战：坐标系统与Codex辅助开发

最近我在用 Godot 搭一个六边形地块 demo，项目代号叫 Summer Engine。起初我以为最麻烦的是“怎么画出六边形”，真正开始写以后才发现，画六边形只是入门，真正决定这个 demo 能不能往下走的是坐标系统、邻居关系，以及怎么把随机生成逻辑拆清楚。更现实的问题是：我并没用纯手写搞定所有代码，而是让 Codex 参与了大半生成、改错和重构的过程。这也让这次实验变成了一个很有意思的话题——用 AI 编程助手做一个小型程序化生成工具，哪些环节能提升效率，哪些环节反而要盯紧。

如果你也想做一个六边形地块 demo，或者想试试用 Codex 辅助 Godot 开发，这篇文章会把我的完整思路、可复用的代码骨架和踩过的坑都梳理一遍。

1. 六边形地块生成，难的不是“画六边形”

1.1 为什么选程序化生成，而不是手动摆地块

如果你只是想要一张固定的六边形地图，那最简单的方式其实是手动摆放。比如在 Godot 里直接用 TileMap 的六边形 tile，或者干脆把几个 Polygon2D 拖进场景，花不了多少时间。但问题在于，一旦地图规模变大、地块类型变多、需要生成多张地图对比效果，手动摆放就完全失控了。

程序化生成解决的不是“下一次手绘”的问题，而是“反复生成、可调参、可复现”的问题。你希望修改一个半径参数地图就能重新生成，希望改变随机种子得到完全不同的布局，希望以后接入噪声算法或者根据玩法规则自动决定地块类型。这些需求本质上都指向同一个方向：把地图当作数据，而不是一堆静态节点。

这也是我要做的六边形地块 demo 的核心定位：不是去做一张精美的成品地图，而是先把生成流程打通。

1.2 六边形地图的真正地基：坐标系统和邻居关系

很多第一次做六边形的人会把所有精力放在几何形状上，觉得六边形六个顶点算对就行。但六边形网格和四边形网格最大的区别是坐标系统。四边形可以直接用行列索引，六边形如果也硬套二维数组，邻居关系会变得非常别扭。

常见方案里有立方体坐标、轴向坐标、偏移坐标。我个人建议在 Godot 里做地块生成时，先使用轴向坐标，也就是用(q, r)两个值表示一个格子。它的直观性不如偏移坐标，但处理邻居关系时特别干净。一个六边形格子有六个邻居，在轴向坐标下它们的增量是固定的：

(+1, 0), (+1, -1), (0, -1), (-1, 0), (-1, +1), (0, +1)

如果你用二维数组直接基于行和列去找邻居，处理奇偶行的时候很容易写错边界条件。而轴向坐标天然规避了“奇偶行偏移”的问题。

所以，整个 demo 的地基不是画一个六边形，而是先定义好坐标系统，然后让所有节点都从坐标计算出来。

2. 先搭一个最小工程，再让 AI 参与

2.1 环境准备：Godot 与 Summer Engine 骨架

这里先说明一下 Summer Engine 的定位。按这次项目的标题，我把它理解为一套基于 Godot 的实验性项目骨架，用于快速跑六边形地块类的生成 demo。实际写代码时，你并不需要额外安装特殊引擎，用 Godot 4.x 建一个空工程，按同样结构组织脚本就行。

我建议的最小工程结构分为三层：

• scenes/：存放主场景，比如Main.tscn。
• scripts/：放 GDScript，核心生成逻辑写在hex_grid.gd。
• config/：放生成参数，可以用 Godot 的 Resource 或 JSON 保存半径、地块尺寸、随机种子等。

为什么要单独拆一个config目录？因为程序化生成真正有价值的不是写死一组参数，而是让参数可配置。后面你想对比不同地块大小或不同种子时，不需要改代码，只需要改配置文件。

在 Summer Engine 骨架里，我保留了一个入口场景，根节点是Node2D，挂载HexGrid脚本。第一版不需要太复杂，能显示网格即可。

2.2 用 Codex 生成第一个生成脚本

接下来是 Codex 的用武之地。我的做法不是让它背着一个大需求直接输出完整项目，而是先给它一个小而明确的任务：生成一个 GDScript 脚本，挂在 Node2D 上，根据半径生成一组六边形 Polygon2D。

下面是我实际使用的一个提示词示例：

在 Godot 4 的 GDScript 中，写一个挂在 Node2D 上的脚本： 1. 使用轴向坐标 (q, r) 2. 提供函数 axial_to_world(coord, hex_size) 计算中心点坐标 3. 使用 radius 参数控制六边形地图半径 4. 为每个格子创建一个 Polygon2D，颜色随机 5. 输出完整可运行的 gdscript 代码

Codex 能很快给出初稿。但这不意味着可以直接用，你需要检查几个关键点：

• 是否使用了 Godot 4 的语法，比如构造函数Vector2i、PackedVector2Array。
• 是否处理了轴向坐标的范围条件。
• 是否每个格子都创建了独立节点，节点数量是否合理。

我实际拿到的初稿里，坐标范围条件经常是简化版，比如只限制q和r各自在[-radius, radius]，这会导致地图形状变成六边形还是菱形的问题。所以，AI 初稿只能作为起点，边界逻辑要靠人工修正。

2.3 最小验证：先跑通单块六边形

在生成完整网格之前，我建议你先做最小验证：只生成一个六边形。这一步能快速排查几何计算、Polygon2D 属性和颜色设置是否正确。

下面是我整理后的最小代码示例，也适合作为 Summer Engine 的第一版骨架：

extends Node2D @export var hex_size: float = 40.0 func _ready() -> void: var center := Vector2.ZERO var polygon := create_hex_polygon(center) add_child(polygon) func create_hex_polygon(center: Vector2) -> Polygon2D: var points := PackedVector2Array() for i in range(6): var angle_deg := 60.0 * i - 30.0 var angle_rad := deg_to_rad(angle_deg) var point := center + Vector2(hex_size * cos(angle_rad), hex_size * sin(angle_rad)) points.append(point) var polygon := Polygon2D.new() polygon.polygon = points polygon.color = Color(0.4, 0.7, 1.0) return polygon

这里先不要急着生成几十个格子。确认一个六边形正常显示，再去扩展网格，能省掉大量定位问题的时间。

实操提醒：单个六边形显示出来以后，要多检查它是不是“正六边形”。如果你发现顶点角度或尺寸计算有问题，先停下来修正，不要带着错误几何继续生成。

3. 从单块到网格：把生成逻辑拆成可复用模块

3.1 轴向坐标与像素坐标的换算

当单个六边形没问题后，下一步就是把坐标系统建立起来。六边形网格里，最常见的换算公式是将轴向坐标(q, r)转换为屏幕上的中心点坐标。

在 Godot 的 2D 坐标系里，我常用的公式如下：

func axial_to_world(coord: Vector2i, hex_size: float) -> Vector2: var x := hex_size * sqrt(3.0) * (coord.x + coord.y / 2.0) var y := hex_size * 3.0 / 2.0 * coord.y return Vector2(x, y)

这个公式的推导并不复杂。六边形横排时，水平间距是sqrt(3) * hex_size，垂直间距是1.5 * hex_size。但因为六边形是交错排列的，每一行的x坐标还要根据r偏移半个水平间距。所以坐标转换的核心就是这两个系数。

在让 Codex 生成这段逻辑时，它通常能直接给出正确公式，但你需要提醒它确认是“水平平顶”还是“尖顶”六边形。上面的公式对应尖顶六边形，也就是上下有两个顶点。如果你想要平顶六边形，坐标公式和顶点偏移角度都要换一套。

3.2 生成地图数据，而不是直接生成节点

一个常见的误区是：在_ready()里循环创建 Polygon2D，一口气把地图节点全部生成出来。这种方式对 demo 没问题，但一旦地图范围变大，节点数量会迅速膨胀，编辑器性能和运行时性能都会变差。

更好的做法是分两步：先生成地图数据，再把数据转成可视节点。

地图数据可以是二维数组、字典，或者自定义的CellData资源。对六边形网格，我建议用字典以Vector2i为 key，这样很容易进行邻居查找、地块类型判断和后续扩展。

class CellData: var coord: Vector2i var terrain_type: int var color: Color

生成地图数据时，只关心每个格子有什么属性，不需要关心它怎么显示。等数据完整了，再遍历数据创建 Polygon2D。这样，显示层和数据层就解耦了。

这个设计虽然看起来多了一层，但对于程序化生成非常关键。因为后面你大概率会想换一种显示方式，比如把 Polygon2D 换成 TileMap，或者加上地块边框、图标、资源点。如果数据和显示混在一起，每次改动都会很痛苦。

3.3 用随机种子和噪声控制地块类型

一个程序化生成 demo 如果每次生成结果完全随机，那它的价值会大打折扣。因为你很难判断某种地图布局是参数引起的，还是纯粹运气好。所以，随机种子必须第一时间加入。

在 Godot 里，可以用seed()全局函数，或者给随机数生成器传入种子。更稳妥的做法是把种子作为配置文件里的一个字段，这样每次跑出的地图可以复现。

地块类型也不应该每次都用randi() % n拍脑袋。更好的方式是使用简单的值噪声或柏林噪声。对 demo 来说，引入完整噪声库可能有点重，但至少可以用几个正弦波叠加来伪造地形趋势，或者使用随机数加平滑滤波器。

比如，我先给每个格子一个基础海拔值，然后根据阈值划分成水域、平原、丘陵、山地。这样比单纯随机分布看起来更自然。

Codex 在这个环节非常适合用来“生成噪声采样函数”，但你要说清楚输入输出，比如：

写一个 GDScript 函数，输入 Vector2i，输出 0.0 到 1.0 之间的浮点数，使用简单的伪随机采样，并且相同的输入永远返回相同输出。

注意，这里重点是“相同的输入永远返回相同输出”，这需要你自己设计哈希或基于种子的采样逻辑，而不是直接用randi()。AI 生成的随机函数经常忽略可复现性，需要你提醒。

4. Codex 辅助开发的正确用法与容易踩的坑

4.1 给 Codex 写清楚“输入-输出-约束”

我这次实验最大的感受是，Codex 能不能帮上忙，很大程度上取决于你给它的上下文是否清晰。如果你只丢一句“写一个六边形地块生成”，它很难知道你用的是轴向坐标还是偏移坐标，也不知道你要显示成 Polygon2D 还是 TileMap。

有效的提问方式，至少要包含四层信息：

• 环境：Godot 4、GDScript、2D 节点。
• 输入：轴向坐标范围、六边形尺寸、随机种子。
• 输出：节点结构、颜色范围、是否需要返回地图数据。
• 约束：可复现、性能优先、不引入外部插件。

举个例子：

用 Godot 4 GDScript 写一个六边形网格生成器： - 类名 HexGrid，继承 Node2D - 导出变量 radius 和 hex_size - 使用轴向坐标 (q, r)，范围受 radius 限制成六边形 - 生成每个格子的中心点坐标，并创建 Polygon2D - 地块颜色由每格 value 决定，value 来自可复现的伪随机函数 - 提供 get_cells() 方法返回字典，key 是 Vector2i，value 是颜色 - 不要使用 TileMap

这样写，Codex 返回的代码基本能用。但“基本能用”不等于“无坑”，你仍然要人工检查范围条件、坐标公式和节点释放逻辑。

4.2 常见报错排查链路：从 Codex 到 Godot

使用 Codex 过程中，最常见的不是它给不出代码，而是它给的代码和当前 Godot 环境不匹配。我自己遇到过的典型报错包括：

• 提示找不到Vector2i构造方式，多半是 GDScript 版本写成了 Godot 3。
• 报错Parser Error: Unexpected token，通常是缩进或者函数签名有误。
• 运行后没有显示任何多边形，需要检查_ready()是否被正确调用、节点是否被添加到场景树。

如果你遇到类似问题，不要急着重新生成一遍代码。我建议按照下面的链路排查：

1. 先看报错行，确认是不是语法或 API 版本问题。
2. 再看输入参数，半径、尺寸是否合法，是否有除零风险。
3. 然后看场景树，确认生成脚本挂载到了正确的节点上。
4. 最后看数据结构，PackedVector2Array是否非空，坐标是否在合理范围。

Codex 生成的代码报错时，你可以把完整报错信息贴给它，让它先解释再修复。但注意，有些反复报错可能不是代码问题，而是项目路径、脚本类名冲突或者编辑器缓存问题。这时候 AI 帮不上忙，只能靠你从 Godot 的环境层面排查。

提醒：接入 Codex CLI 时，如果出现类似 “unable to locate the codex cli binary” 的提示，通常不是项目代码问题，而是本机 Codex 命令行工具的路径没有被正确配置。先确认终端里能否直接调用 codex 命令，再把 IDE 或编辑器里的 Codex 路径指向正确位置。

4.3 不要盲目接受 AI 生成的代码

这次实验最有价值的一点，不是 Codex 帮我写出了多少行代码，而是倒逼我弄清楚了自己到底要什么。因为如果你不懂六边形坐标系统，你连怎么纠正 AI 的代码都不知道。

举个例子：Codex 很容易生成一个看起来很完美的循环：

for q in range(-radius, radius + 1): for r in range(-radius, radius + 1): # ...

这段代码本身没有语法错误，但它生成的网格实际上是菱形，不是六边形。只有当你理解六边形半径在立方体坐标下的约束条件，你才知道需要加一层判断，把q + r的范围限制住。

正确写法应该是：

for q in range(-radius, radius + 1): for r in range(max(-radius, -q - radius), min(radius, -q + radius) + 1): # 有效格子

这种边界条件，AI 有可能写对，但也容易漏。所以，重点不是“让 AI 替你写代码”，而是“让 AI 替你加速验证想法，但你需要掌握核心约束”。

5. 把 demo 变成一个小型生成器：批量、性能与数据驱动

5.1 从单场景生成到批量地图实例

当单张地图生成稳定后，下一步通常是批量生成多张地图，或者多次重新生成对比效果。这时，最需要解耦的是“生成逻辑”和“展示逻辑”。

在我最终的 Summer Engine 骨架里，HexGrid类不再在_ready()里直接生成节点，而是提供两个方法：

• generate_data(seed_value)：生成地图数据，存到字典。
• render()：根据当前数据创建节点显示。

这样的好处是，你可以先循环生成 10 份地图数据，只取其中符合条件的一份渲染；也可以同一份数据渲染成不同样式。

Codex 非常适合帮你生成批量调用脚本，但你要明确告诉它，哪些数据要缓存，哪些数据要释放。否则测试多轮后内存会一直涨。

5.2 性能监控与节点数量

如果你的地图半径只有 3，那生成的格子数是几十个，完全不需要考虑性能。但半径到了 10，格子数会超过 300；半径 20，就会上千。如果每个格子都是一个独立的 Polygon2D，一百个节点性能还可接受，上千个节点则可能会卡。

性能优化有几个常见方向：

• 使用单张 MultiMesh 或_draw()自绘，减少节点数量。
• 只创建需要显示的格子，卸载远处格子。
• 使用 TileMapLayer，利用 TileMap 的渲染优化。

对于 demo 来说，优先采用最简单的方式：先控制半径，加一个节点数量统计，超过一定数量就提示。这不是过度设计，而是让你在开发过程中对生成规模有感知。

我通常会加一个运行时统计：

print("生成格子数: ", cells.size())

看到数量，你才知道当前参数是否适合继续调大。

5.3 用配置文件沉淀地图规则

程序化生成最怕的是“这次生成很好看，但不知道下次怎么复现”。为了避免这种局面，我建议把生成规则、种子、地块阈值、颜色表全部放到配置文件里。

Summer Engine 的config/目录下可以放一个 JSON 文件：

{ "radius": 6, "hex_size": 40, "seed": 2024001, "terrain_thresholds": { "water": 0.3, "plain": 0.6, "hill": 0.85, "mountain": 1.0 } }

读取配置后，生成逻辑按照配置执行。这样你每次调整参数都是在改数据，而不是改代码。Codex 在这个阶段可以帮你写一个简单的 JSON 解析和参数绑定脚本，但同样要检查类型转换和缺失字段的处理。

注意：配置文件不是越多越好。对 demo 来说，只保留真正会影响生成结果的参数。把颜色表也放进去是可以的，但不要把不会变的常量全部塞进去，否则配置反而变成新的负担。

6. 总结这次实验留给我的三件事

回到标题里的那个 demo，Summer Engine + Codex 的组合，最打动我的不是“AI 帮我写代码”本身，而是它把程序化生产的流程拆得更加清楚。

第一，程序化生成六边形地块，核心不是六边形几何，而是坐标系统和数据结构。没有这个地基，后面所有扩展都会踩坑。

第二，Codex 这类工具的真正价值是让你更专注地表达意图。它能把一个清晰的描述变成能跑的代码，也能在报错时快速给出修改方向。但它不能替你理解边界条件、坐标范围、数据结构，这些需要你心里有数。

第三，demo 和生产之间的差距，通常在参数配置、数据与显示分离、可复现性、节点数量控制这些不起眼的环节。代码能跑不等于方案就成立。

如果你也想做类似的实验，我的建议是：先手工跑通单个六边形，再用 Codex 生成网格初稿，然后亲手补充边界条件，最后把参数拆到配置文件。这个顺序看着慢，实际是节省时间最快的路径。