World tools¶
Terrain, foliage, water queries and spatial placement on real geometry.
15 tools in the world category. Badges: read-only tools never change the project; mutating tools are undoable and attributed; open-world tools reach outside the engine and MCP clients ask before running them.
| Tool | Summary |
|---|---|
raycast |
Cast a ray into the scene and get the first mesh hit (triangle-accurate): entity, point, surface normal and distance. |
place_on_surface |
Move entities straight down (or up) so the bottom of their bounds rests on the geometry below them. |
scatter |
Procedurally place many copies of an entity or prefab in an area — forests, rocks, coins, crowds. |
water_query |
Height and normal of the animated water surface (FFT ocean) at points — for floating boats, buoys and debris, or placing a pier above the waves. |
tilemap_paint |
Edit a tilemap layer: set individual cells, fill a rectangle, flood-fill a region, or clear. |
tilemap_from_ascii |
Build or update a tilemap from an ASCII map — the fastest way to lay out a level. |
tilemap_inspect |
Read a tilemap as ASCII per layer (with a legend of tile ids and counts), its size, tileset, terrains and the merged collision rectangles (world units, relative to the map's top-left; x right, y up) — what a physics body or a pathfinder needs. |
terrain_create |
Create a large heightfield terrain: an island with beaches, a tropical coast, alpine peaks, a canyon, desert dunes, rolling hills or a mountain valley. |
terrain_generate |
Regenerate a terrain's heights from new generator parameters (shape, seed, heights, featureSize, ridges, warp, erosion, thermal, terraces, beachWidth, seaLevel), then re-paint its layers. |
terrain_sculpt |
Sculpt a terrain with brush strokes at world (x, z) positions: raise / lower (strength in meters), flatten (toward target world height; plateaus, roads, building pads), smooth, noise (rougher ground), set. |
terrain_paint |
Paint a material layer (by index or name) onto a terrain with brush strokes at world (x, z): sand paths, dirt patches, grass clearings. |
terrain_layers |
Replace a terrain's material layers and re-paint them from their rules (height/slope/noise). |
terrain_undo |
Step back the last terrain_sculpt / terrain_paint / terrain_generate / terrain_layers on a terrain (heights and weights; component fields use the regular undo). |
terrain_query |
Terrain height, normal, slope (degrees) and dominant layer at world (x, z) points, plus terrain stats. |
foliage_add |
Grow GPU-instanced foliage and ground detail over a terrain (or over scene meshes in an area): grass, tall grass, dune grass, flowers, ferns, beach pebbles, shells, small rocks, boulders — or any mesh/asset as a custom layer (trees, bushes from downloads). |
raycast¶
Ray cast read-only
Cast a ray into the scene and get the first mesh hit (triangle-accurate): entity, point, surface normal and distance. Give origin+direction in world space, or a pixel x,y of an editor-camera capture (width/height). Use it to find the ground height, check line of sight, or aim placements.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
origin |
number[3] | World-space ray origin | ||
direction |
number[3] | Ray direction (default straight down [0,-1,0]) | ||
x |
number | Pixel x in an editor-camera capture | ||
y |
number | Pixel y in an editor-camera capture | ||
width |
integer | Capture width (default 768) | ||
height |
integer | Capture height (default 432) | ||
exclude |
integer | string[] | Entities to ignore |
place_on_surface¶
Drop onto surface mutating
Move entities straight down (or up) so the bottom of their bounds rests on the geometry below them. Great after placing props roughly on uneven terrain. One undo step.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
entities |
integer | string[] | yes | Entities to drop | |
offset |
number | Extra height above the surface (default 0) |
scatter¶
Scatter copies mutating
Procedurally place many copies of an entity or prefab in an area — forests, rocks, coins, crowds. Deterministic for a given seed. Random yaw/scale ranges, minimum spacing, and optional snapping to the surface below. All copies go under a new group entity; the whole operation is one undo step.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
source |
integer | string | Entity to copy (with its children) | ||
prefab |
string | …or a prefab asset path | ||
count |
integer | yes | How many copies (1-2000) | |
center |
number[3] | Area center (default origin) | ||
size |
number[] | Area [width, depth] in meters (default [20, 20]) | ||
radius |
number | Use a circular area with this radius instead of size | ||
min_distance |
number | Minimum spacing between copies (default 0) | ||
yaw |
any | Yaw degrees: number or [min, max] (default [0, 360]) | ||
scale |
any | Uniform scale multiplier: number or [min, max] (default 1) | ||
on_surface |
boolean | Drop copies onto the geometry below (default true) | ||
surface |
integer | string | Only land on this entity (e.g. the terrain) | ||
seed |
integer | Random seed (default 1) | ||
group |
string | Name of the group entity (default "<source> scatter") |
water_query¶
Water height read-only
Height and normal of the animated water surface (FFT ocean) at points — for floating boats, buoys and debris, or placing a pier above the waves. Uses the current effects time.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
points |
number[][] | yes | Points as [x, z] pairs |
tilemap_paint¶
Paint tiles mutating
Edit a tilemap layer: set individual cells, fill a rectangle, flood-fill a region, or clear. tile is a tile id (1-based in the tileset, 0 = empty), a terrain from tilemap.autotile (auto-tiled: edges and corners pick the right tiles), or a tileset tile name. Cells are [column, row] from the top-left. One undo step. Example: {"entity": "Level", "action": "fill", "rect": [0, 14, 40, 2], "tile": "ground"}
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
entity |
integer | string | yes | Tilemap entity | |
layer |
string | Layer name (created if missing; default: the first layer) | ||
action |
string | yes | set cells, fill rect, flood at, clear rect/layer | set fill flood clear |
tile |
integer | string | Tile id, terrain or tile name | ||
cells |
integer[][] | [[x, y], ...] for set | ||
rect |
integer[] | [x, y, w, h] for fill/clear | ||
at |
integer[] | [x, y] for flood/set | ||
flip_x |
boolean | Mirror placed tiles horizontally | ||
flip_y |
boolean | Mirror placed tiles vertically |
tilemap_from_ascii¶
Tilemap from ASCII mutating
Build or update a tilemap from an ASCII map — the fastest way to lay out a level. Each line is a row (top first); legend maps characters to tile ids, terrain names (auto-tiled) or tileset tile names; ' ' and '.' are empty unless the legend says otherwise. Creates the entity if it doesn't exist. Without a tileset, tiles render as flat colors so you can block out levels before the art exists. solid marks this layer for collision (true = every tile, "tiles" = only solidTiles). Example: {"name": "Level", "tileset": "art/tiles.png", "tile_size": 16, "autotile": {"ground": {"mode": "blob47", "first": 1}}, "legend": {"#": "ground", "^": 60}, "solid": true, "map": "..........\n...^^.....\n##########"}
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
map |
string | yes | ASCII rows separated by newlines | |
legend |
object | yes | character -> tile id | terrain | tile name | |
entity |
integer | string | Existing tilemap entity to update | ||
name |
string | Name for a new tilemap entity (default "Tilemap") | ||
layer |
string | Layer to write (default "ground") | ||
tileset |
string | Tileset image or *.tileset.json | ||
tile_size |
integer | Tile size in tileset pixels (default 16) | ||
cell_size |
number | World units per cell (default 1) | ||
position |
number[3] | Top-left corner of the map in the world (new maps) | ||
autotile |
object | Terrains to add: {"wall": {"mode": "blob47", "first": 33}} | ||
solid |
boolean | string | true | "tiles" | false | ||
solid_tiles |
array | string | Tile ids that collide ([3, "10-20"]) | ||
sorting_layer |
string | Sorting layer of the map | background midground default foreground overlay |
|
z |
number | This layer's z offset (parallax / 2.5D ordering) |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "tilemap_from_ascii",
"arguments": {
"name": "Level",
"tileset": "art/tiles.png",
"tile_size": 16,
"autotile": {
"ground": {
"mode": "blob47",
"first": 1
}
},
"legend": {
"#": "ground",
"^": 60
},
"solid": true,
"map": "..........\n...^^.....\n##########"
}
}
}
tilemap_inspect¶
Inspect tilemap read-only
Read a tilemap as ASCII per layer (with a legend of tile ids and counts), its size, tileset, terrains and the merged collision rectangles (world units, relative to the map's top-left; x right, y up) — what a physics body or a pathfinder needs.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
entity |
integer | string | yes | Tilemap entity | |
layer |
string | Only this layer | ||
max_rects |
integer | Collision rectangles to list (default 64) |
terrain_create¶
Create terrain mutating
Create a large heightfield terrain: an island with beaches, a tropical coast, alpine peaks, a canyon, desert dunes, rolling hills or a mountain valley. Natural shapes come from warped noise plus hydraulic and thermal erosion; material layers (sand, grass, soil, rock, snow...) are auto-painted by height and slope, with procedural textures unless you pass your own layer textures (e.g. downloaded photoscans). water: true adds an FFT sea at sea level and wet sand along the shore. Then add foliage_add (grass, pebbles, shells, rocks). Your own relief: pass heightmap (a grayscale PNG). Examples: {"preset":"island_beach","size":600,"water":true}, {"heightmap":"maps/continent.png","size":4000,"generator":{"minHeight":-40,"maxHeight":160}}.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
name |
string | Entity name (default "Terrain") | ||
preset |
string | Starting shape and layers | island_beach tropical_coast alpine canyon desert_dunes rolling_hills mountain_valley flat |
|
size |
number | Square extent in meters (default 512) | ||
resolution |
integer | Height samples per side: 257, 513 (default), 1025, 2049 | ||
position |
number[3] | World position of the terrain center | ||
seed |
integer | Random seed (each seed is a different landscape) | ||
generator |
object | Overrides: shape, minHeight, maxHeight, featureSize (m), ridges, warp, erosion, thermal, terraces, beachWidth, seaLevel, heightmap, detailNoise | ||
layers |
array | Material layers (see the terrain component) | ||
heightmap |
string | Grayscale image (16-bit PNG, 8-bit PNG or square .r16) whose values 0..1 map to generator minHeight..maxHeight: hand-made or scripted continents, real-world-style relief. Row 0 is the -Z edge. Erosion/thermal from the generator still apply. | ||
water |
boolean | Add an ocean at sea level with a wet shoreline (island/coast presets) |
terrain_generate¶
Regenerate terrain mutating
Regenerate a terrain's heights from new generator parameters (shape, seed, heights, featureSize, ridges, warp, erosion, thermal, terraces, beachWidth, seaLevel), then re-paint its layers. Undo with terrain_undo.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
entity |
integer | string | yes | Terrain entity | |
generator |
object | Parameters to change | ||
seed |
integer | New seed |
terrain_sculpt¶
Sculpt terrain mutating
Sculpt a terrain with brush strokes at world (x, z) positions: raise / lower (strength in meters), flatten (toward target world height; plateaus, roads, building pads), smooth, noise (rougher ground), set. Great for carving a beach cove, a path, a harbor basin or a flat spot for a village. Undo with terrain_undo.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
entity |
integer | string | yes | Terrain entity | |
strokes |
object[] | yes | Brush strokes, applied in order |
skywalker call terrain_sculpt '{"entity": "Terrain", "strokes": [{"x": 30, "z": 10, "radius": 14, "strength": 2, "mode": "flatten", "target": 4.0}, {"x": -20, "z": 0, "radius": 9, "strength": 1.5, "mode": "lower"}, {"x": 0, "z": -30, "radius": 25, "strength": 0.6, "mode": "noise"}]}' --project my_game
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "terrain_sculpt",
"arguments": {
"entity": "Terrain",
"strokes": [
{
"x": 30,
"z": 10,
"radius": 14,
"strength": 2,
"mode": "flatten",
"target": 4.0
},
{
"x": -20,
"z": 0,
"radius": 9,
"strength": 1.5,
"mode": "lower"
},
{
"x": 0,
"z": -30,
"radius": 25,
"strength": 0.6,
"mode": "noise"
}
]
}
}
}
terrain_paint¶
Paint terrain layer mutating
Paint a material layer (by index or name) onto a terrain with brush strokes at world (x, z): sand paths, dirt patches, grass clearings. Foliage restricted to a layer follows the paint. Undo with terrain_undo.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
entity |
integer | string | yes | Terrain entity | |
layer |
any | yes | Layer index (0 = base) or name | |
strokes |
object[] | yes | Brush strokes |
terrain_layers¶
Terrain layers mutating
Replace a terrain's material layers and re-paint them from their rules (height/slope/noise). Each layer: {name, texture, normalMap, ormMap (project paths, e.g. downloaded photoscans) or texgen (sand, grass, dirt, rock, noise), color/tint, roughness, tiling (meters per repeat), triplanar (cliffs), heightMin, heightMax, slopeMin, slopeMax, noise, sharpness}. Base layer first; later layers paint over earlier ones where their rules match. Hand-painted weights are replaced unless auto_paint is false.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
entity |
integer | string | yes | Terrain entity | |
layers |
array | yes | Up to 8 layers | |
auto_paint |
boolean | Recompute weights from the rules (default true) |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "terrain_layers",
"arguments": {
"entity": "Island",
"layers": [
{
"name": "sand",
"texgen": "sand",
"tiling": 4
},
{
"name": "grass",
"texgen": "grass",
"heightMin": 2,
"slopeMax": 30
},
{
"name": "rock",
"texgen": "rock",
"slopeMin": 35,
"triplanar": true
}
]
}
}
}
terrain_undo¶
Undo terrain edit mutating
Step back the last terrain_sculpt / terrain_paint / terrain_generate / terrain_layers on a terrain (heights and weights; component fields use the regular undo).
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
entity |
integer | string | yes | Terrain entity |
terrain_query¶
Query terrain read-only
Terrain height, normal, slope (degrees) and dominant layer at world (x, z) points, plus terrain stats. Use it to place villages on flat ground, find the shoreline, or check where cliffs are.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
entity |
integer | string | Terrain entity (default: any terrain under each point) | ||
points |
number[][] | [x, z] pairs |
foliage_add¶
Add foliage mutating
Grow GPU-instanced foliage and ground detail over a terrain (or over scene meshes in an area): grass, tall grass, dune grass, flowers, ferns, beach pebbles, shells, small rocks, boulders — or any mesh/asset as a custom layer (trees, bushes from downloads). Presets: meadow_grass, tall_grass, dune_grass, beach_pebbles, shells, flowers, ferns, rocks_small, boulders, custom. Layer fields: mesh, color, density (/m²), scaleMin/Max, slopeMin/Max, heightMin/Max (world y), terrainLayer (a terrain layer's index or name, e.g. "grass"; only where that layer is painted), wind, cullDistance, castShadows, clumping. Dense layers stream in around the camera. Heavy meshes (trees, bushes, rocks) switch to octahedral impostors in the distance automatically; tune with impostorDistance (m; 0 auto, -1 off), impostorResolution and impostorFrames, or impostors:false. Example: {"entity":"Island","layers":[{"preset":"dune_grass","heightMin":1.5},{"preset":"shells","heightMax":1.2}]}. Hand-placed instances: a layer with points draws exactly those (buildings of a distant city, a row of cypresses, lamp posts along a quay) with the same instancing, LODs and impostors: [x, y, z, yaw?, scale?] or {position, rotation [pitch, yaw, roll], scale (number or [x, y, z]), tint}; snapToSurface: true makes y an offset above the ground. Example: {"entity":"Terrain","name":"Far City","layers":[{"prefab":"models/house_a.prefab.json","wind":0,"cullDistance":3000,"snapToSurface":true,"points":[[40,0,-120,90],[52,0,-118,0,1.2]]}]}.
| Argument | Type | Required | Description | Values |
|---|---|---|---|---|
entity |
integer | string | yes | Terrain entity to grow on (foliage becomes its child), or any entity for scene mode | |
layers |
array | yes | Layers: {preset, ...overrides} or full custom layers | |
name |
string | Foliage entity name (default "Foliage") | ||
area |
number[3] | Scene mode: extent in meters around the entity | ||
seed |
integer | Placement seed |