/terrain

name: unity-terrain
description: Operate on Unity Terrain. 操作 Unity Terrain。

Triggers

• Creating or editing terrain
• Sculpting or smoothing heightmap
• Painting terrain texture layers
• 创建或编辑地形、雕刻或平滑高度图、绘制地形纹理层

Unity Terrain Skills

Guardrails

**Operating Mode** (v1.9 three-tier):

• **Approval** (default): query skills (`terrain_get_info`, `terrain_get_height`) run directly. Create/modify skills (`terrain_create`, `terrain_set_height`, `terrain_set_heights_batch`, `terrain_add_hill`, `terrain_generate_perlin`, `terrain_smooth`, `terrain_flatten`, `terrain_paint_texture`) are FullAuto — on `MODE_RESTRICTED`, run the grant protocol; `/permission/grant` executes the skill server-side and returns the result.
• **Auto** / **Bypass**: SemiAuto and FullAuto run directly.
• This module contains **no** Delete / PlayMode / Reload / `RiskLevel="high"` skills — nothing auto-classifies as forbidden. To remove a terrain delete the asset via `asset_delete` (subject to its own forbidden rules).

> **Note**: All sculpt/paint operations require an existing Terrain in the scene, or use `terrain_create` to generate one.

**DO NOT** (common hallucinations):

• `terrain_set_texture` does not exist → use `terrain_paint_texture` with layer index and brush parameters
• `terrain_add_tree` / `terrain_add_grass` do not exist → these require Unity Terrain tools or custom scripts
• `terrain_set_size` does not exist → terrain dimensions are set at creation via `terrain_create`
• `terrain_import_heightmap` / `terrain_set_heights` do not exist → use `terrain_set_heights_batch` with a 2D heights array (`[z][x]` values 0-1)

**Routing**:

• For terrain material → use `material` module on terrain's material
• For objects on terrain → use `gameobject` module to create/place objects

Skills Overview

| Skill | Description | |-------|-------------| | `terrain_create` | Create new Terrain with TerrainData | | `terrain_get_info` | Get terrain size, resolution, layers | | `terrain_get_height` | Get height at world position | | `terrain_set_height` | Set height at normalized coords | | `terrain_set_heights_batch` | Batch set heights in region | | `terrain_add_hill` | ⭐ Add smooth hill with radius and falloff | | `terrain_generate_perlin` | ⭐ Generate natural terrain using Perlin noise | | `terrain_smooth` | ⭐ Smooth terrain to reduce sharp edges | | `terrain_flatten` | ⭐ Flatten terrain to target height | | `terrain_paint_texture` | Paint texture layer at position |

---

Skills

terrain_create

Create a new Terrain GameObject with TerrainData asset.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `name` | string | No | "Terrain" | Terrain name | | `width` | int | No | 500 | Terrain width (X) | | `length` | int | No | 500 | Terrain length (Z) | | `height` | int | No | 100 | Max terrain height (Y) | | `heightmapResolution` | int | No | 513 | Heightmap resolution (power of 2 + 1) | | `x`, `y`, `z` | float | No | 0 | Position |

**Returns**: `{success, name, instanceId, terrainDataPath, size, position}`

terrain_get_info

Get terrain information.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No* | Terrain name | | `instanceId` | int | No* | Instance ID |

*If neither provided, uses first terrain in scene

**Returns**: `{success, name, instanceId, position, size, heightmapResolution, alphamapResolution, detailResolution, terrainLayerCount, layers}`

terrain_get_height

Get terrain height at world position.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `worldX` | float | Yes | World X coordinate | | `worldZ` | float | Yes | World Z coordinate | | `name` | string | No | Terrain name |

**Returns**: `{success, worldX, worldZ, height, worldY}`

terrain_set_height

Set height at normalized coordinates.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `normalizedX` | float | Yes | X position (0-1) | | `normalizedZ` | float | Yes | Z position (0-1) | | `height` | float | Yes | Height value (0-1) | | `name` | string | No | Terrain name | | `instanceId` | int | No | Terrain instance ID |

**Returns**: `{success, normalizedX, normalizedZ, height, pixelX, pixelZ}`

terrain_set_heights_batch

⚠️ **BATCH SKILL**: Set heights in rectangular region.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `startX` | int | Yes | Start X pixel index | | `startZ` | int | Yes | Start Z pixel index | | `heights` | float[][] | Yes | 2D array [z][x] with values 0-1 | | `name` | string | No | Terrain name | | `instanceId` | int | No | Terrain instance ID |

**Returns**: `{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

⭐ **RECOMMENDED**: Add a smooth, natural-looking hill to the terrain.

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `normalizedX` | float | Yes | - | X position (0-1) | | `normalizedZ` | float | Yes | - | Z position (0-1) | | `radius` | float | No | 0.2 | Hill radius (0-1, relative to terrain size) | | `height` | float | No | 0.5 | Hill height (0-1) | | `smoothness` | float | No | 1.0 | Smoothness factor (higher = smoother) | | `name` | string | No | null | Terrain name | | `instanceId` | int | No | 0 | Terrain instance ID |

**Returns**: `{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):