snap_actor_to_ground
Destructive
Drops a single editor-world actor to the ground, using a downward line trace and falling back to heightmap sampling when the trace misses.
Instructions
Drop ONE editor-world actor straight down until its bounds bottom rests on whatever is below -- meshes, BSP or the landscape. It line-traces first and, because headless traces routinely MISS the landscape, falls back to sampling the heightmap so the actor still lands; sampled_from tells you which path answered. Use place_actor_on_terrain when the ground is definitely the landscape and you want no trace at all, batch_place_actors_on_terrain for many actors.
Returns: { actor: actor JSON, hit: bool, landed: bool, sampled_from: 'trace'|'heightmap', hit_actor?: string, hit_distance?: number }
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| actor_name | Yes | Name of the actor to snap (editor world). | |
| trace_distance | No | Optional downward trace distance in cm; defaults to 10000 | |
| align_to_surface | No | When true, rotate actor to match the surface normal (trace hits only; the heightmap fallback has no normal); defaults to false | |
| fallback_heightmap | No | When true (default) and the downward line trace misses (headless traces routinely miss the landscape), fall back to sampling the landscape heightmap at the actor's XY (same sampler as place_actor_on_terrain) so the actor still lands. Set false to require a real trace hit. |