spatial_query
Perform spatial queries in Roblox including raycasting, ground detection, placement checks, area scanning, and collision detection.
Instructions
[PRO] Spatial queries: raycast, find ground, check placement, multi-raycast, scan area, find flat areas, find spawn positions, analyze walkable, spatial map, find empty space, get bounds, snap to grid, check collision.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | [PRO] Spatial action. raycast: single ray. find_ground: ground below point. check_placement: collision-free placement check. multi_raycast: batch rays. scan_area: heightmap generation. find_flat: flat areas for building. find_spawn: spawn positions. analyze_walkable: walkability grid. spatial_map: all BasePart positions. find_space: empty space for object. bounds: bounding box. snap_grid: snap position to grid. collision: AABB collision check. | |
| origin | No | Ray origin as Vector3. Used by: raycast. | |
| direction | No | Ray direction and length as Vector3. Used by: raycast. | |
| maxDistance | No | Maximum distance for ground search. Used by: find_ground. Default: 1000. | |
| position | No | Position as Vector3. Used by: find_ground (cast from here), check_placement (center), collision (hypothetical position). | |
| size | No | Size as Vector3. Used by: check_placement (object size), find_space (required space size), scan_area (area X/Z dimensions). | |
| filterType | No | Raycast filter type. Used by: raycast, multi_raycast. Default: "Exclude". | |
| filterList | No | Instance paths to filter. Used by: raycast, multi_raycast, find_ground, check_placement, scan_area. Alias: filterInstances. | |
| filterInstances | No | Instance paths to filter (alias for filterList). Used by: raycast, multi_raycast, find_ground, check_placement, scan_area. | |
| ignoreWater | No | Ignore terrain water. Used by: raycast, multi_raycast. Default: false. | |
| rays | No | Array of ray specifications. Used by: multi_raycast. Max 50 rays. | |
| center | No | Center point for area scan. Used by: scan_area. | |
| area | No | Bounding box for analysis. Used by: analyze_walkable. Contains min/max. | |
| searchArea | No | Bounding box for search. Used by: find_flat, find_spawn, find_space. | |
| minSize | No | Minimum flat area size. Used by: find_flat. | |
| maxSlope | No | Maximum slope in degrees. Used by: find_flat (default: 10), analyze_walkable (default: 45). | |
| resolution | No | Grid resolution in studs. Used by: scan_area, analyze_walkable. Default: 4. | |
| gridSize | No | Grid snap size in studs. Used by: snap_grid (default: 4), find_space (default: 4). | |
| path | No | Instance path. Used by: bounds (optional), snap_grid (required), collision (required), spatial_map (rootPath alias). | |
| paths | No | Multiple instance paths for batch bounds. Used by: bounds. | |
| tolerance | No | Height variation tolerance in studs. Used by: find_flat. | |
| gridSnap | No | Grid snap size. Alias for gridSize. | |
| axes | No | Axes to snap. Used by: snap_grid. Default: ["x","y","z"]. Use ["x","z"] for horizontal only. | |
| ignorePaths | No | Instance paths to ignore in collision check. Used by: collision. | |
| offset | No | Vertical offset for ground position. Used by: find_ground. Default: 0. | |
| rotation | No | Rotation in degrees. Used by: check_placement. | |
| checkGround | No | Verify ground support for placement. Used by: check_placement. Default: true. | |
| spawnSize | No | Size of spawning entity. Used by: find_spawn. Default: {x:4, y:5, z:4}. | |
| minSpacing | No | Minimum distance between spawn positions. Used by: find_spawn. Default: 10. | |
| preferOutdoor | No | Prefer open sky positions. Used by: find_spawn. Default: false. | |
| count | No | Number of results to find. Used by: find_spawn. Default: 10. | |
| characterHeight | No | Character height for clearance checks. Used by: analyze_walkable. Default: 5. | |
| maxStepHeight | No | Maximum step height. Used by: analyze_walkable. Default: 2. | |
| rootPath | No | Root path for spatial map scan. Used by: spatial_map. Default: "game.Workspace". | |
| includeModels | No | Include Model bounding boxes. Used by: spatial_map. Default: true. | |
| maxResults | No | Maximum results. Used by: spatial_map (default: 500), scan_area (default: 500), find_flat (default: 10). | |
| padding | No | Minimum distance from other objects. Used by: find_space. Default: 1. |