企业官网建设流程全解析

• 游戏开发
• 桌面应用

本文深入剖析 TEdit（Terraria Map Editor）内置的generate脚本对象——一套面向过程化世界生成的完整 API。该 API 覆盖树木、矿脉、洞穴、液体湖泊、七大生态区、地牢/丛林神庙等结构以及地表装饰等四十余个方法，全部支持撤销追踪，可由 JavaScript 或 Lua 脚本直接调用。读完本文，你将掌握如何用脚本从零构建一个接近 Terraria 原生密度与地貌特征的世界，并能读懂仓库自带的worldgen-showcase.js19 步世界生成示例。

1. 概述：generate对象与 Feature Tracker

TEdit 的脚本引擎（基于 JintScriptEngine.cs 与 LuaScriptEngine.cs）在脚本执行上下文中注入一个generate对象，供过程化世界创建使用。该对象在 ScriptApi.cs 中通过Generate = new GenerateApi(world, undo, selection)创建，因而所有修改都写入 TEdit 的撤销管理器（IUndoManager），可随时 Undo。脚本中对应的 TypeScript 声明位于 tedit-api.d.ts 的declare const generate段。

GenerateApi是一个 partial class，按职责拆分为五个源文件（均位于src/TEdit/Scripting/Api/）：

文档中附带的 Feature Tracker 对比了 TEdit 已实现的 worldgen 功能与 Terraria 原生世界生成的对应关系：表面地形剖面（TerrainPass 随机游走）、土/石填充、岩石/泥土散布（TileRunner blob）、小孔洞、土层与岩层洞穴、表面竖井、草地蔓延、矿脉（Cu/Fe/Ag/Au）、粘土/淤泥、水湖/岩浆池/蜂蜜（Lakinater）、指数深度海洋（TuneOceanDepth）、冰/丛林/沙漠/蘑菇/腐化/猩红/神圣生态区、地狱、地牢、丛林巨树、蘑菇树、大理石/花岗岩/蜘蛛洞穴、蜂巢、金字塔、生命树、地下房屋、丛林神庙、藤蔓/植物/陶罐/钟乳石/生命水晶/向日葵/荆棘、地形平滑等均已完成；漂浮岛、NPC 房屋、附魔剑冢、地狱堡垒、宝石洞穴、微光湖、困难模式矿脉、化石、叶绿矿脉、地表小屋、恶魔祭坛、暗影珠/猩红之心、地牢家具/宝箱、地表沙丘、丛林神龛、冰生态宝箱、发光苔藓洞穴、蜂巢幼虫、灰烬树、珊瑚礁等则列入Phase 2。

2. 生态区几何：shape 参数与 Biome Shapes

所有生态区方法都接受可选的shape参数来控制区域几何，底层判定实现为 GenerateApi.Biomes.cs 中的IsInsideShape：它将行列坐标归一化到以(x + w/2, y)为中心、横向±w/2、纵向0..1的坐标系，再套用不同的判定公式，并为每个方块在边界处叠加 ±0.12 的随机抖动（(_rand.NextDouble() - 0.5) * 0.12），形成自然毛边。

每个生态区有合理默认值：冰trapezoid、腐化diagonalLeft、猩红diagonalRight、神圣diagonalLeft、蘑菇ellipse、沙漠ellipse、丛林rectangle。

3. 树木 API：tree/forest/forestInSelection/listTreeTypes

3.1 方法签名与语义

• tree(type, x, y) → bool：在基座坐标(x, y)种植单棵树，y是地面高度，树向上生长；返回是否成功放置。
• forest(types, x, y, w, h, density?) → int：在矩形内种植多棵树，从types数组中随机选种；树干之间最少保持 4 格间距（Terraria 要求 3 格空隙，以免x±1处的枝干重叠相邻树干，见 GenerateApi.cs 的minSpacing = 4）；density默认0.15，范围0.0–1.0（内部用Math.Clamp收紧），实际间距在minSpacing与1/density之间随机浮动。返回种树数量。
• forestInSelection(types, density?) → int：与forest相同，但使用当前选区矩形（无选区时返回 0）。
• listTreeTypes() → object[]：返回所有支持树种{ name, tileId }。

3.2 支持树种表

类型名匹配使用StringComparer.OrdinalIgnoreCase（大小写不敏感）。从源码可看出三类生长实现：标准树（GrowStandardTree）逐段放置树干并随机树干帧（frameType0–9，对应frameX0/22/44 与frameY0/66…），中段随机生成左/右/双侧枝（frameType 5/6/7），顶部放置树冠帧（12/13 概率正常树冠frameX=22，1/13 概率秃顶frameX=0），底部按两侧地面情况生成根部扩展（PlaceBase的 4 种 baseStyle）；棕榈树（GrowPalmTree）随高度累积 ±2 的frameY倾斜量形成自然弯度；蘑菇树（GrowMushroomTree）则在顶部放置U=36的菌盖。

4. 地形原语：TileRunner 家族与液态湖

这些是生态区、洞穴、矿脉、湖泊共用的底层算法，全部在 GenerateApi.WorldGen.cs 中实现。

4.1tileRunner(x, y, strength, steps, tileType, speedX?, speedY?)

移植自 Terraria 的WorldGen.TileRunner——一个“漫游画家”算法，从(x, y)出发迭代steps次，每次以线性衰减的半径填充菱形斑点（半径 =strength × remaining/total，判定|dx|+|dy| < strength×0.5×(1±15% 抖动)），位置随速度矢量游走（速度随机抖动并被钳制在 ±1）。放置模式下会跳过帧重要方块（家具、植物等WorldConfiguration.GetTileProperties(...).IsFramed为真的方块），避免破坏已放置结构。测试 GenerateApiTests.cs 中的TileRunner_PlacesTilesInSolidArea、TileRunner_SkipsFrameImportantTiles、TileRunner_WithSpeedBias_PlacesTilesAwayFromStart分别验证了落块、跳帧与速度偏置行为。

4.2tunnel(x, y, strength, steps, speedX?, speedY?)

与tileRunner同算法但清除方块而非放置，用于生成自然洞穴隧道（clearMode=true时调用Tile.ClearTile()）。

4.3lake(x, y, liquidType?, strength?)

移植自 Terraria 的WorldGen.Lakinater，分两遍完成：第一遍以25–50×strength初始半径、向下偏置速度（velY钳制在0.5–1.5）雕刻不规则空腔并清空液体；第二遍从每列底部向上填充液体——因为 TEdit 没有液体物理，代码按空腔高度在regionMinY + 20%处计算水位线，下方填LiquidAmount=255满液、上方留空气袋。参数：liquidType默认"water"，可选"lava"、"honey"、"shimmer"（大小写不敏感，其他值回退到 water）；strength默认1.0，为尺寸乘数，且有20% 概率（_rand.Next(5)==0）整体 1.5× 放大。

4.4oreVein(oreName, x, y, size?)

tileRunner的命名便捷封装：size为"small"（0.5×）、"medium"（1.0×）、"large"（2.0×），对默认 strength/steps 等比例缩放（steps 至少为 1）。支持 18 种矿石（数据表见 GenerateApi.cs 的OreTypes）：

listOreTypes()返回同样的{ name, tileId }列表，测试断言其长度为 18 且包含 chlorophyte/luminite。

4.5findSurface(x, yStart, yEnd) → int

在x列从yStart向下扫描到yEnd，返回第一个激活实心方块的 y 坐标（即地表），未找到返回-1。它是所有生态区方法定位地表的关键辅助函数（Forest、IceBiome、Corruption等内部均调用它）。

5. 生态区 API：转换规则与 Terraria 对照

所有生态区方法返回被转换的方块数，内部先把IsInsideShape判定通过的区域按 tile 类型映射表做“石头→XX、泥土→XX、草→XX”等转换，再叠加各自的结构特征。

5.1iceBiome(x, y, w, h, shape?) → int

默认"trapezoid"（越深越宽）。转换：stone→冰(161)、dirt→雪(147)、grass→雪、mud→雪泥(224)、sand→硬化沙(397)；土墙(2)→雪墙(40)。随后额外散布max(3, w*h/5000)个冰洞斑点（TileRunnerCore填冰）与max(2, w*h/6000)个雪泥斑点。Terraria 对照：由 WorldGen.cs 的 12+ 趟生成，形状采用每行 ±4/±5 漂移的随机游走并相对上一行平滑，范围从worldSurface（雪顶）到lavaLine-140（雪底），包含薄冰覆水、裸露宝石、冰柱钟乳石、冰小堆与冰冻宝箱等子结构。

5.2corruption(x, y, w, depth, shape?) → int

默认"diagonalLeft"。转换：stone/dirt→黑檀石(25)、grass→腐化草(23)、sand→黑檀沙(112)、ice→紫冰(163)；土墙→黑檀石墙(3)。随后在生态区内用ChasmRunner开凿max(1, w/40)条垂直裂隙——这是WorldGen.ChasmRunner的移植：宽度 7–11 格、向下速度钳制0.5–2.5、宽度每步衰减 0.1，在下半程（remaining < steps/2）有 1/3 概率向左右分支出ChasmRunnerSideways横向侧支（宽 7–12、长 20–40 步）。Terraria 对照：由GenPassNameID.CorruptionAndCrimson生成，地表条带约 200–600 格宽，竖井150+rng(150)步，侧支在worldSurface+20起，另有暗影珠(31) 2×2、恶魔祭坛(26)、死亡草(24)、腐化藤蔓(636)与荆棘(22)等装饰。

5.3crimson(x, y, w, depth, shape?) → int

默认"diagonalRight"。转换：stone/dirt→猩红石(203)、grass→猩红草(199)、sand→猩红沙(234)、ice→红冰(200)；土墙→猩红石墙(83)。裂隙比腐化更宽更有机（CrimsonChasmRunner：宽 8–15、圆距离判定、向下速度钳制0.3–2.0）。Terraria 对照：CrimStart→CrimVein→CrimPlaceHearts，地表宽度与腐化相同，地下由半径 15–25 的下潜段连到半径 40–55 的地下腔室，5–8 条CrimVein放射（半径 15–25、长 100–150 步）在端点放置猩红之心(31 frameX=36)，另有恶毒蘑菇植物(201)、猩红藤蔓(205)。

5.4hallow(x, y, w, h, shape?) → int

默认"diagonalLeft"。转换：stone→珍珠石(117)、grass→神圣草(109)、sand→珍珠沙(116)、ice→粉冰(164)、dirt→神圣泥土(477)；洞穴墙→神圣洞墙(28)。Terraria 对照：原生 worldgen 不生成神圣之地——它由困难模式激活（initializeHardMode）时的GERunner(i, 0, speedX, speedY, good=true)创造，半径 200–250 的对角 V 臂扫过世界，同时把腐化/猩红方块转回自然或神圣变体；神圣藤蔓(382)从土墙洞穴垂下。

5.5mushroomBiome(x, y, w, h, shape?) → int

默认"ellipse"。第一遍把 stone/dirt/grass→泥(59)，并在空气方块里也补蘑菇墙(80)（保证生态判定）；第二遍把暴露在空气中的泥转成蘑菇草(70)，再散布max(2, w*h/4000)个泥块斑点。Terraria 对照：ShroomPatch每生态位调 6 次，Y 距离乘 2.3 形成扁椭圆（宽高比约 4–5:1），水平半径 80–100、垂直 20–26，随世界尺寸缩放；内部 20% 挖空并铺蘑菇墙(80)，20%–40% 填泥(59)，泥脉经TileRunner带下偏速度生成，巨型蘑菇树从蘑菇草(70)上长出，位置在rockLayer+50到maxTilesY-300，每世界最多 50 棵。

5.6jungle(x, y, w, h, shape?, ditherWidth?) → int

默认"rectangle"——如 Terraria 一样填满整个纵向空间。边缘抖动（dithering）代替硬边界：ditherWidth（默认 15，设为 0 即硬边）定义了边缘概率衰减带，代码按edgeDist/ditherWidth线性衰减、随机跳过。第一遍 stone/dirt/grass→泥(59)、土墙→泥墙(15)；第二遍暴露泥→丛林草(60)；随后开凿max(5, w*h/3000)条丛林洞穴并散布泥块斑点（扩展进抖动带）。Terraria 对照：单一连续生态，主TileRunner以 mud(59)、strength=400–600×worldScale、steps=10000、speedY=-20, noYChange=true从(maxTilesY+rockLayer)/2向上喷射，生成巨型有机边缘；子结构含蜂巢(225/蜂巢墙86)、丛林神龛、蜥蜴神庙(226/墙87)、活木巨树(383/384)；装饰有丛林植物(61)、丛林藤蔓(62)、2×2 丛林植物(233)。

5.7desert(x, y, w, h, shape?) → int

默认"ellipse"（贯穿地图高度的长椭圆）。按深度分三带：ty < y + h/4为沙(53)、ty < y + h×3/4为硬化沙(397)、更深为砂岩(396)；跳过帧重要方块；地下补砂岩墙(187)；开凿max(2, w*h/10000)条沙漠洞穴。Terraria 对照：表面沙丘用SandMound.cs的精确公式sqrt(1−t⁴)，4200 宽世界约为 320 格宽、510–680 格深（极深）；三垂直带为表面沙丘穹顶→沙漠过渡→地下蜂巢（Voronoi/metaball 簇算法），4 类入口（Chambers/Anthill/LarvaHole/Pit 各 33%）；子结构有金字塔、绿洲、沙漠屋（宝箱 style 10）、化石(404)。

5.8 洞穴类：marbleCave(x, y, strength?)/graniteCave(x, y, strength?)/spiderCave(x, y, strength?)

• 大理石洞：3–5 次游走斑点填大理石(367) + 大理石墙(178)（半径约 strength×1.3 的PlaceWallBlob），再挖 2–4 条内洞。strength默认 40.0。
• 花岗岩洞：同上填花岗岩(368)/花岗岩墙(180)，内洞更多（3–6 条，strength 4–9）。strength默认 40.0。
• 蜘蛛洞：先挖 2–4 条小隧道，再铺radius = strength×1.5的蜘蛛墙(62)，并在墙内空格以 2/3 概率填蛛网(51)。strength默认 10.0。

6. 结构 API：从海洋到地狱

6.1ocean(direction?, oceanWidth?, maxDepth?) → int

TuneOceanDepth的移植。direction：-1左/西边缘、1右/东边缘（默认 1）；oceanWidth默认max(80, world×15%)格；maxDepth默认 80 格。核心特征：

• 指数深度曲线：depth = maxDepth × (1 − e^(−3.5 × distFromBeach))，岸边浅、边缘深；
• 每列沙床抖动 ±3（累积钳制 ±8）形成自然海底；
• 沙从沙床线向下延伸 8–15 格封死既有洞穴/缝隙（找到沙床下方第一个实心方块再深埋 8 格）；
• 海面到沙床的水柱填LiquidAmount=255水；
• 海底散布max(5, oceanWidth/6)个珊瑚(81)。

6.2underworld(yStart?) → int

六趟算法（GenerateApi.Structures.cs）：

1. 天花板/岩浆地板剖面：天花板每列 ±3 随机游走（钳制yStart±30），岩浆地板每列 ±10（钳制worldH−80 … worldH−25）；
2. 灰烬填充：天花板到世界底部全部填灰烬(57)；
3. 洞穴雕刻：max(10, w/80)条大型水平隧道 +max(20, w/40)条纹理小洞 +烟囱开口（每列 1/50 概率，3–7 格宽、30–80 格高向上打通到岩石层）；
4. 狱岩石矿脉：max(15, w/40)处TileRunnerCore填狱岩石(58)；
5. 黑曜石：max(8, w/60)处靠近岩浆面（±15）填黑曜石(56)；
6. 岩浆填充：岩浆地板以下所有开放空格填LiquidAmount=255的岩浆。

yStart默认取worldH×0.8（即岩浆线），与上层石层无缝衔接。Terraria 对照：5-pass 层结构，灰烬天花板在maxTilesY−150..190、岩浆地板在maxTilesY−40..70，另有 HellFort（5×10 黑曜石砖房间网格）与困难模式灰烬树等子结构。

6.3beehive(x, y, size?)

椭圆蜂巢外壳：radiusX=size、radiusY=size×0.7，填蜂巢块(225)+蜂巢墙(86)；内部挖空 70% 尺寸的空腔，下 60% 填蜂蜜（ty > y − innerY×0.4处填LiquidAmount=255蜂蜜）。size默认随机 15–30。

6.4pyramid(x, y, height?)

以(x, y)为塔尖的砂岩砖(151)金字塔，每行宽度 = 行号，逐行下扩；内部开凿对角走廊（步长 3:2 比例斜向推进）通向末端8–14 × 6–10的宝藏室（铺砂岩砖墙 10）。height默认随机 40–80。

6.5livingTree(x, y, height?)

活木巨树：树干宽 4–8 格、自height×60%处向上逐段收窄，内部挖空并铺活木墙(78)；向下伸出 2–4 条随机游走树根（长 15–40 步、横向速度钳制 ±1.5）；顶部铺192叶方块 canopy（椭圆判定的稀疏树冠）。height默认随机 40–80。

6.6dungeon(x, y, direction?, style?)

分支式“房间-走廊”布局：先开凿 5 格宽、15–30 格深的入口竖井，再用BFS 队列放置 10–20 个房间（每个 10–20×8–14），每房间 1–3 条走廊（向下/左/右三向随机，带轻微漂移，水平走廊后常接 5–15 格下坠段加深纵深），高房间（>8 格）内 2/3 概率放平台(19)。style：0=蓝地牢砖(41)/蓝墙(7)、1=绿地牢砖(43)/绿墙(8)、2=粉地牢砖(44)/粉墙(9)。Terraria 对照：DungeonCrawler.MakeDungeon顺序游走算法放置 34–42 个房间（常规/蠕虫状/活树状/BiomeSquare/L 形等），走廊分 Normal(4–5 宽)/Long/Tall/Intersection，入口必为地表竖井；房间放置后还有 13+ 全局特征趟：尖刺(48)、门(10)、平台(19)、书架(101)、桌椅、锁住的金地牢宝箱(21 style 2)、灯笼、旗帜、枝形吊灯、喷泉、裂纹地牢砖、蛛网(51)等；未击败骷髅王前进入会生成地牢守卫。

6.7jungleTemple(x, y, w?, h?)

简化版蜥蜴神庙：整个矩形填蜥蜴砖(226)+蜥蜴墙(87)，再按12–18 × 8–14的单元网格挖空房间，每个房间从底/左/右三侧随机开 3 格门洞。w默认 80–150、h默认 60–100。

6.8undergroundHouse(x, y, style?)

简单地下屋：8–16 × 5–8的房间（边缘填墙、内部挖空铺墙），底部一行放平台。style：0=木(30/墙4)、1=石(1/墙1)、2=地牢蓝(41/墙7)。

7. 装饰 API

这些实现都遵循“随机采样 + 重试 +SaveAndSet撤销写入”的统一模式，且与树木一样在放置后手动设置帧坐标（U/V），保证与游戏原版贴图一致。

8. 实战：worldgen-showcase.js的 19 步完整世界生成管线

仓库自带的 worldgen-showcase.js 演示了完整流程。运行前提：通过File > New World（任意尺寸）新建世界，脚本依赖 New World 对话框设置的world.surfaceLevel、world.rockLevel；文件头部注明“For a Small world (4200×1200): ~15,000 cave calls, ~6,000 ore veins, lakes, lava pools, trees”。其 19 步依次为：

1. 地形剖面（TerrainPass 移植）：按 5 类特征段（0=Plateau/1=Hill/2=Dale/3=Mountain/4=Valley）随机游走生成逐列surfaceY，特征段持续rand(5,40)列；两端 8% 为平直海滩、中央 4% 强制高原（出生点）；地表钳制在17%–26%世界高度，岩层在surface+6%..35%内随机游走。
2. 地形填充：每列地表到岩层填 DIRT、岩层到lavaLine(80%h)填 STONE。
3. 散布斑块：面积×1.5e-4个石入土、同数土入石、面积×3e-5个泥斑（全部走tileRunner）。
4. 小孔洞：面积×0.0015处，每处两次tunnel（strength 2–5/8–15）。
5. 土层洞穴：面积×3e-5处，strength 5–15、steps 30–200。
6. 岩层洞穴：面积×0.00013处，strength 6–20、steps 50–300。
7. 地表洞穴：按列数比例生成小型/中型竖井、大型三分支与水平隧道（利用speedY控制方向）。
8. 草地蔓延：逐列向下扫描裸露 DIRT 顶格换成 GRASS。
9. 矿脉：铜/铁各 3 深度区、银 2 区、金仅深层，按区密度6e-5 ~ 2e-4乘面积投放tileRunner。
10. 粘土与淤泥：面积×5e-5粘土（地表–岩层）+面积×3e-5淤泥（深层）。
11. 地下湖：w×0.01处lake(x, y, "water", 0.8+rand×0.8)。
12. 岩浆池：w×0.005处lake(x, y, "lava", 0.6+rand×0.6)。
13. 蜂蜜池：max(3, w×0.002)处lake(x, y, "honey", 0.4+rand×0.4)。
14. 地狱：generate.underworld()（默认岩浆线自动衔接）。
15. 海洋：generate.ocean(-1, w×0.12, h×0.07)与ocean(1, …)生成左右两侧。
16. 生态区：冰（trapezoid，右 65% 起 25% 宽）、丛林（rectangle 全纵深）、沙漠（ellipse 全纵深）、腐化（diagonalLeft）、猩红（diagonalRight）、神圣（diagonalLeft）、蘑菇（ellipse）、max(2, w×0.001)个大理石/花岗岩/蜘蛛洞。
17. 结构：max(1, jungleW×0.02)个蜂巢 +max(5, w×0.005)个地下屋。
18. 森林：地表["oak","oak","oak","sakura","willow"]、丛林["jungle"]、蘑菇["mushroom"]三种forest调用。
19. 装饰：藤蔓（森林/丛林/猩红）、植物（森林/丛林）、陶罐、钟乳石、生命水晶、向日葵、荆棘（腐化/猩红）、飞镖机关、最后smoothWorld整体平滑。

脚本全程使用log.print/log.progress输出每步进度与统计（洞穴调用数、矿脉数、湖泊数、生态区转换数、树数等），最后打印总结；全程任意一步产生的修改都可撤销。该脚本与文档中的 Feature Tracker 一一对应，是理解 API 的最佳可运行范本。

9. 测试与验证

仓库在 GenerateApiTests.cs 中为generateAPI 提供单元测试，可直接验证实现事实：

• ListOreTypes_ReturnsAllOres：断言 18 种矿石齐全（copper 到 luminite）；
• ListOreTypes_HasCorrectTileIds：校验 copper=7、gold=8 等 tile ID；
• TileRunner_PlacesTilesInSolidArea：在实心区域放置后能查找到对应类型方块；
• TileRunner_SavesUndoForModifiedTiles：验证修改均写入撤销栈（_undo.SavedTiles非空）；
• TileRunner_SkipsFrameImportantTiles：宝箱(21)等帧重要方块不会被覆盖；
• TileRunner_WithSpeedBias_PlacesTilesAwayFromStart：speedX/speedY偏置使落点偏离起点；
• Tunnel_ClearsTilesInSolidArea等隧道与生态区相关测试覆盖清除语义。

这组测试与 tedit-api.d.ts 的generate类型声明互为印证，表明该 API 是引擎层（ScriptApi暴露、JintScriptEngine/LuaScriptEngine执行）正式支持的一等公民。

10. 使用建议与限制

• 运行方式：在 TEdit 的脚本侧栏（Scripting Sidebar，见 ScriptingSidebarViewModel.cs）中加载worldgen-showcase.js，对新建空世界执行即可；也可用.lua编写等效脚本（引擎支持 Lua，见 LuaScriptEngine.cs）。
• 依赖世界属性：forest/ocean/underworld等依赖world.surfaceLevel、world.rockLevel、world.height，请先通过 New World 对话框创建世界。
• 撤销保证：所有方法通过_undo.SaveTile记录每次改动，可整体撤销；但脚本是批量修改，建议在空世界或测试副本上运行。
• 与原生 Terraria 的差异：TEdit 无液体物理，lake直接按水位线填充；jungleTemple、dungeon等为文档明确标注的“简化”实现；Phase 2 功能（漂浮岛、神庙完全版等）尚未提供。
• 帧数据一致：树木、植物、陶罐、生命水晶等放置后会手动写 U/V 帧坐标，请勿用普通方块替换逻辑覆盖，否则渲染会出现错帧。

通过generateAPI，你可以把 TEdit 当成一个可编程的“Terraria 世界生成沙盒”：在几分钟内用脚本重建原生级别的地形、生态区、结构与装饰，并反复迭代直到满意——这正是该 API 相对手工逐格绘制最大的价值所在。

• 游戏开发
• 桌面应用