unity-terrain

**调用本模块中的任何技能前：**如果你打算根据技能名称或描述猜测参数后调用技能，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获取参数定义，则可直接进行 dryRun。

触发条件

• 创建或编辑地形
• 雕刻或平滑高度图
• 绘制地形纹理层
• 创建或编辑地形、雕刻或平滑高度图、绘制地形纹理层

Unity 地形技能

防护规则

操作模式（v1.9 三层模式）：

• Approval（默认）：查询技能（terrain_get_info、terrain_get_height）可直接运行。创建/修改技能（terrain_create、terrain_set_height、terrain_set_heights_batch、terrain_add_hill、terrain_generate_perlin、terrain_smooth、terrain_flatten、terrain_paint_texture）属于 FullAuto——遇到 MODE_RESTRICTED 时，运行授权流程；/permission/grant 会在服务端执行该技能并返回结果。
• Auto / Bypass：SemiAuto 和 FullAuto 可直接运行。
• 本模块不包含任何 Delete / PlayMode / Reload / RiskLevel="high" 技能——没有技能会被自动归类为禁止项。要移除地形，请通过 asset_delete 删除资源（受其自身的禁止规则约束）。

注意：所有雕刻/绘制操作都要求场景中存在 Terrain，或者使用 terrain_create 创建一个。

不要（常见幻觉）：

• terrain_set_texture 不存在 → 使用 terrain_paint_texture，并设置图层索引和笔刷参数
• terrain_add_tree / terrain_add_grass 不存在 → 这些操作需要使用 Unity Terrain 工具或自定义脚本
• terrain_set_size 不存在 → 地形尺寸在创建时通过 terrain_create 设置
• terrain_import_heightmap / terrain_set_heights 不存在 → 使用 terrain_set_heights_batch，并传入二维高度数组（[z][x] 值为 0-1）

路由：

• 对于地形材质 → 使用 material 模块处理地形材质
• 对于地形上的对象 → 使用 gameobject 模块创建/放置对象

技能概览

技能	描述
terrain_create	创建带有 TerrainData 的新 Terrain
terrain_get_info	获取地形尺寸、分辨率和图层
terrain_get_height	获取世界位置处的高度
terrain_set_height	设置归一化坐标处的高度
terrain_set_heights_batch	批量设置区域内的高度
terrain_add_hill	⭐ 添加具有半径和衰减的平滑山丘
terrain_generate_perlin	⭐ 使用 Perlin 噪声生成自然地形
terrain_smooth	⭐ 平滑地形以减少尖锐边缘
terrain_flatten	⭐ 将地形压平至目标高度
terrain_paint_texture	在指定位置绘制纹理图层

---

技能

terrain_create

创建带有 TerrainData 资源的新 Terrain GameObject。

参数	类型	必填	默认值	描述
name	string	否	"Terrain"	Terrain 名称
width	int	否	500	Terrain 宽度（X）
length	int	否	500	Terrain 长度（Z）
height	int	否	100	Terrain 最大高度（Y）
heightmapResolution	int	否	513	高度图分辨率（2 的幂 + 1）
x, y, z	float	否	0	位置

返回值：{success, name, instanceId, terrainDataPath, size, position}

terrain_get_info

获取地形信息。

参数	类型	必填	描述
name	string	否*	Terrain 名称
instanceId	int	否*	实例 ID

*如果两者都未提供，则使用场景中的第一个 Terrain

返回值：{success, name, instanceId, position, size, heightmapResolution, alphamapResolution, detailResolution, terrainLayerCount, layers}

terrain_get_height

获取世界位置处的地形高度。

参数	类型	必填	描述
worldX	float	是	世界 X 坐标
worldZ	float	是	世界 Z 坐标
name	string	否	地形名称

返回：{success, worldX, worldZ, height, worldY}

terrain_set_height

设置归一化坐标处的高度。

参数	类型	必填	描述
normalizedX	float	是	X 位置（0-1）
normalizedZ	float	是	Z 位置（0-1）
height	float	是	高度值（0-1）
name	string	否	地形名称
instanceId	int	否	地形实例 ID

返回：{success, normalizedX, normalizedZ, height, pixelX, pixelZ}

terrain_set_heights_batch

⚠️ 批量操作技巧：设置矩形区域内的高度。

参数	类型	必填	描述
startX	int	是	起始 X 像素索引
startZ	int	是	起始 Z 像素索引
heights	float[][]	是	值为 0-1 的二维数组 [z][x]
name	string	否	地形名称
instanceId	int	否	地形实例 ID

返回：{success, startX, startZ, modifiedWidth, modifiedLength, totalPointsModified}

# Example: Create a 10x10 hill
heights = [[0.5 - abs(x-5)/10 - abs(z-5)/10 for x in range(10)] for z in range(10)]
call_skill("terrain_set_heights_batch", startX=50, startZ=50, heights=heights)

terrain_add_hill

⭐ 推荐：向地形添加平滑、自然的山丘。

参数	类型	必填	默认值	描述
normalizedX	float	是	-	X 位置（0-1）
normalizedZ	float	是	-	Z 位置（0-1）
radius	float	否	0.2	山丘半径（0-1，相对于地形尺寸）
height	float	否	0.5	山丘高度（0-1）
smoothness	float	否	1.0	平滑度系数（值越高越平滑）
name	string	否	null	地形名称
instanceId	int	否	0	地形实例 ID

返回：{success, centerX, centerZ, radius, height, affectedArea}

# Add a large smooth hill at center
call_skill("terrain_add_hill",
    normalizedX=0.5, normalizedZ=0.5,
    radius=0.3, height=0.6, smoothness=2.0)

# Add multiple hills for varied terrain
for i in range(5):
    call_skill("terrain_add_hill",
        normalizedX=random.uniform(0.2, 0.8),
        normalizedZ=random.uniform(0.2, 0.8),
        radius=random.uniform(0.1, 0.25),
        height=random.uniform(0.3, 0.7))

terrain_generate_perlin

⭐ 推荐：使用 Perlin 噪声算法生成自然地形。

参数	类型	必填	默认值	描述
scale	float	否	20.0	噪声缩放（值越低，地形特征越大）
heightMultiplier	float	否	0.3	高度强度（0-1）
octaves	int	否	4	细节层数（值越大，细节越多）
persistence	float	否	0.5	每个倍频的振幅衰减
lacunarity	float	否	2.0	每个倍频的频率增量
seed	int	否	0	随机种子（0 = 随机）
name	string	否	null	地形名称

返回：{success, resolution, scale, heightMultiplier, octaves, persistence, lacunarity, seed}

# Generate rolling hills
call_skill("terrain_generate_perlin",
    scale=25.0, heightMultiplier=0.4, octaves=4)

# Generate mountainous terrain
call_skill("terrain_generate_perlin",
    scale=15.0, heightMultiplier=0.6, octaves=6, persistence=0.6)

# Generate with specific seed for reproducibility
call_skill("terrain_generate_perlin",
    scale=20.0, heightMultiplier=0.5, seed=12345)

terrain_smooth

⭐ 平滑地形高度，以减少尖锐边缘并形成自然过渡。

参数	类型	必填	默认值	描述
normalizedX	float	是	-	X 位置（0-1）
normalizedZ	float	是	-	Z 位置（0-1）
radius	float	否	0.1	平滑半径（0-1）
iterations	int	否	1	平滑次数
name	string	否	null	地形名称
instanceId	int	否	0	地形实例 ID

返回：{success, centerX, centerZ, radius, iterations, affectedArea}

# Smooth a specific area
call_skill("terrain_smooth",
    normalizedX=0.5, normalizedZ=0.5,
    radius=0.2, iterations=3)

terrain_flatten

⭐ 将某个区域的地形平整至指定高度。

参数	类型	必填	默认值	描述
normalizedX	float	是	-	X 位置（0-1）
normalizedZ	float	是	-	Z 位置（0-1）
targetHeight	float	否	0.5	目标高度（0-1）
radius	float	否	0.1	平整半径（0-1）
strength	float	否	1.0	平整强度（0-1）
name	string	否	null	地形名称
instanceId	int	否	0	地形实例 ID

返回：{success, centerX, centerZ, targetHeight, radius, strength}

# Create a flat plateau
call_skill("terrain_flatten",
    normalizedX=0.5, normalizedZ=0.5,
    targetHeight=0.6, radius=0.15, strength=1.0)

terrain_paint_texture

绘制地形纹理图层。需要预先配置地形图层。

参数	类型	必填	默认值	描述
normalizedX	float	是	-	X 位置（0-1）
normalizedZ	float	是	-	Z 位置（0-1）
layerIndex	int	是	-	地形图层索引（从 0 开始；使用 terrain_get_info 查询可用图层）。超出范围（包括负数）的值会在绘制前被拒绝
strength	float	否	1.0	绘制强度
brushSize	int	否	10	画笔大小（像素）
name	string	否	null	地形名称
instanceId	int	否	0	地形实例 ID

返回：{success, layerIndex, layerName, centerX, centerZ, brushSize, strength}

---

使用示例

import unity_skills

# === Method 1: Quick terrain with Perlin noise (RECOMMENDED) ===
# Create terrain
result = unity_skills.call_skill("terrain_create",
    name="MyTerrain", width=200, length=200, height=50)

# Generate natural terrain with Perlin noise
unity_skills.call_skill("terrain_generate_perlin",
    scale=20.0,           # Larger scale = bigger features
    heightMultiplier=0.4, # Height intensity
    octaves=5,            # More octaves = more detail
    persistence=0.5,
    lacunarity=2.0)

# === Method 2: Add individual smooth hills ===
# Create flat terrain
result = unity_skills.call_skill("terrain_create",
    name="HillyTerrain", width=200, length=200, height=50)

# Add multiple smooth hills
import random
for i in range(8):
    unity_skills.call_skill("terrain_add_hill",
        normalizedX=random.uniform(0.2, 0.8),
        normalizedZ=random.uniform(0.2, 0.8),
        radius=random.uniform(0.15, 0.3),
        height=random.uniform(0.3, 0.6),
        smoothness=1.5)  # Higher = smoother

# Smooth the entire terrain for natural transitions
unity_skills.call_skill("terrain_smooth",
    normalizedX=0.5, normalizedZ=0.5,
    radius=0.5, iterations=2)

# === Method 3: Create specific features ===
# Create a mountain
unity_skills.call_skill("terrain_add_hill",
    normalizedX=0.5, normalizedZ=0.5,
    radius=0.25, height=0.8, smoothness=2.0)

# Create a flat plateau on top
unity_skills.call_skill("terrain_flatten",
    normalizedX=0.5, normalizedZ=0.5,
    targetHeight=0.8, radius=0.1, strength=1.0)

# === Method 4: Manual height control (advanced) ===
import math
heights = []
for z in range(64):
    row = []
    for x in range(64):
        # Distance from center
        dx = (x - 32) / 32
        dz = (z - 32) / 32
        dist = math.sqrt(dx*dx + dz*dz)
        # Smooth hill with cosine falloff
        h = max(0, 0.5 * math.cos(dist * math.pi / 2)) if dist < 1 else 0
        row.append(h)
    heights.append(row)

unity_skills.call_skill("terrain_set_heights_batch",
    startX=100, startZ=100, heights=heights)

# Query height at world position
info = unity_skills.call_skill("terrain_get_height", worldX=100, worldZ=100)
print(f"Height at position: {info['height']}")

工作流集成

所有地形操作都支持工作流撤销/重做：

# Start workflow session
unity_skills.call_skill("workflow_session_start", tag="Create Terrain")

# Create and modify terrain
unity_skills.call_skill("terrain_create", name="TestTerrain")
unity_skills.call_skill("terrain_generate_perlin", scale=20, heightMultiplier=0.5)
unity_skills.call_skill("terrain_add_hill", normalizedX=0.3, normalizedZ=0.3, radius=0.2)

# End session
unity_skills.call_skill("workflow_session_end")

# Later: Undo entire terrain creation
sessions = unity_skills.call_skill("workflow_session_list")
unity_skills.call_skill("workflow_session_undo", sessionId=sessions['sessions'][0]['sessionId'])

---

精确签名

准确的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非此文件。