query · world.construction

Construction placement preview

Validates one authored building footprint against the World grid and retained Construction occupancy without mutating either owner.

world.construction.placement-preview(filters?, cursor?, page_size?) -> query-page

Stable ID: world.construction.placement-preview
Owner: game.construction and sim.world-grid
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.0.0

Usage

Validate one authored building footprint against the current World grid and Construction occupancy without mutating either owner. Use the returned oriented bounds for ui.ghost and require valid before offering designation.

Parameters

filters.definition_id: required authored building identity.
filters.origin_x and filters.origin_y: required signed World-cell origin.
filters.orientation: required integer from zero through three.
cursor: must be zero.
page_size: bounded record limit.

Returns

One detached record containing validity, detail, requested origin, oriented footprint origin and dimensions, orientation, and occupied cell count.

Cost

One content lookup plus one bounded visit per footprint cell.

Fields

ID	Type	Units	Required	Description
`detail`	`string`	none	yes	Specific validation result.
`footprint_cells`	`unsigned-integer`	none	yes	Validated occupied cell count.
`footprint_height_cells`	`unsigned-integer`	World-grid cells	yes	Oriented bounding footprint height.
`footprint_origin_x`	`signed-integer`	World-grid cells	yes	Minimum occupied X coordinate.
`footprint_origin_y`	`signed-integer`	World-grid cells	yes	Minimum occupied Y coordinate.
`footprint_width_cells`	`unsigned-integer`	World-grid cells	yes	Oriented bounding footprint width.
`orientation`	`unsigned-integer`	none	yes	Requested construction orientation.
`origin_x`	`signed-integer`	World-grid cells	yes	Requested footprint origin.
`origin_y`	`signed-integer`	World-grid cells	yes	Requested footprint origin.
`valid`	`boolean`	none	yes	Whether designation can occupy the requested cells.

Errors

Examples

local preview = world.query("world.construction.placement-preview", {page_size = 1, filters = {definition_id = project.definition_id, origin_x = x, origin_y = y, orientation = orientation}})

API history

1.19.0: Read-only construction placement validation added for Phase 19Q9E.