EVEngine/docs/usr/modules/procgen.md

程序化生成模块

脚本入口： eve.Procgen()

按算法名和 Params 生成网格、地图层、图像、法线图或 GPU 纹理。

基本用法

local gen = eve.Procgen();
local p = gen.newParams();
p.setSeed(42); p.setSize(64, 40);
local grid = gen.generate("dungeon.bsp", p);

对象关系与调用时机

Params 描述 seed、尺寸和算法参数；Grid2D 是结果；OutputSpec 决定写入 TileLayer、Image 或 Texture；Procgen 按注册算法名执行。

目标导向指南

生成可玩的地牢层

创建 Params，设置 seed 和尺寸，按需添加算法参数；用 generate("dungeon.bsp", p) 先检查 Grid，也可配置 Output 将结果直接写入 TileLayer。保存 seed 可复现关卡。也可用 generate("wfc.simple", p)（preset=dungeon|cave|terrain）做约束驱动铺贴。

生成等值面网格（Marching Cubes）

local p = gen.newParams();
p.setSeed(1);
p.setInt("resolution", 32);
p.setString("field", "sphere"); // sphere | torus | noise | terrain
local cpu = gen.buildMesh("mesh.marchingcubes", p);
local gpu = gen.generateMesh("mesh.marchingcubes", p, gfx);

生成无缝材质

设置 texture recipe、尺寸、octaves、pixelSize 和 seamless，调用纹理或法线图生成接口；开发期切换 seed 预览，发布时缓存 Texture，不能每帧重新生成。

常见问题

• 未保存 seed，无法复现玩家问题。
• Output palette 缺少算法输出的 tile key。
• 在每帧 update 生成大地图或纹理。

API 快查

下列方法名来自当前 Squirrel 绑定；同一模块创建的辅助对象（例如 World、Body、Source）的方法也列在这里。

• addObject()、addObjectAt()、applyToLayer()、buildMesh()、clearObjects()、fill()、generate()、generateImage()、generateMesh()、generateNormalImage()
• generateTexture()、generateTo()、getAlgorithmCount()、getAlgorithmId()、getCell()、getFloat()、getHeight()、getInt()
• getLayer()、getMeshRecipeCount()、getMeshRecipeId()、getMeta()、getName()、getObjectCount()、getObjectGid()、getObjectHeight()、getObjectName()、getObjectType()
• getObjectWidth()、getObjectX()、getObjectY()、getPalette()、getPaletteGid()、getPath()、getSeed()、getString()
• getTarget()、getTextureRecipeCount()、getTextureRecipeId()、getWidth()、gridToJson()、has()、hasAlgorithm()、hasMeshRecipe()、hasTextureRecipe()
• lastError()、newGrid()、newOutput()、newParams()、resize()、setCell()、setFloat()、setInt()
• setLayer()、setMeta()、setPalette()、setPaletteGid()、setPath()、setSeed()、setSize()、setString()
• setTarget()

使用要点

• 模块对象和它创建的资源对象应保存在全局或实体状态中，不要在每帧重复创建。
• 带 update(dt) 的系统应在 eve_update 调用；绘制方法应在 eve_render 调用。
• 参数约束、默认值和返回类型以对应模块头文件及 addFunc 绑定为准；本文 API 快查与当前源码同步生成。

源码： src/modules/procgen/ 相关测试： 在 test/ 中搜索 procgen；跨模块 hex 关卡见 test/hex_level_simulation.cpp、test/hex_level_data.cpp、examples/hex-levels/。