query · world.settlement

Settlement housing parcels

Returns Settlement-owned physically feasible new-housing parcel alternatives from the latest selected new-construction method, including the exact composite key, placement, source revisions, score components, selection, and rejection reason.

world.settlement.housing-parcels(filters?, cursor?, page_size?) -> query-page

Stable ID: world.settlement.housing-parcels
Owner: game.settlement
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

Inspect the Settlement-owned comparison of complete World parcel alternatives for the currently selected new-construction housing method. Supply settlement_id and optionally household_id. The query cannot reserve land, create construction work, or mutate any gameplay owner.

Parameters

filters.settlement_id: required stable Settlement identity.
filters.household_id: optional stable Household identity associated with the selected construction method.
cursor: optional continuation cursor over stable composite parcel identities.
page_size: bounded parcel-row limit.

Returns

Detached parcel rows with composite identity, source method, Household and building definition, area, origin, rotation variant, footprint and access evidence, source revisions, pressure, service, neighboring-land, material, labor, travel, control, risk, total score, selection or direct rejection, and explanation.

Cost

One exact Settlement lookup plus one bounded traversal of the current retained parcel ledger. Recurring comparison uses the settlement definition's World candidate and proximity-cell visit budgets.

Fields

ID	Type	Units	Required	Description
`access_distance`	`unsigned-integer`	millimeters	yes	Exact path distance.
`access_travel_ticks`	`unsigned-integer`	fixed-ticks	yes	Exact path travel cost.
`access_x`	`signed-integer`	world-cells	yes	Reachable perimeter access x.
`access_y`	`signed-integer`	world-cells	yes	Reachable perimeter access y.
`area_id`	`stable-id`	none	yes	World land-area identity.
`area_revision`	`revision`	none	yes	World land-area revision.
`building_definition_id`	`string`	none	yes	Building definition to place.
`control_certainty`	`unsigned-integer`	basis-points	yes	Current Site control certainty.
`detail`	`string`	none	yes	Direct selection or rejection explanation.
`footprint_cell_count`	`unsigned-integer`	none	yes	Exact occupied-cell count.
`footprint_variant_id`	`string`	none	yes	Pre-rotated footprint identity.
`household_id`	`stable-id`	none	yes	Household requiring the new residence.
`household_revision`	`revision`	none	yes	Household revision assessed.
`infrastructure_revision`	`revision`	none	yes	World infrastructure revision.
`labor_readiness`	`unsigned-integer`	basis-points	yes	Labor readiness.
`material_readiness`	`unsigned-integer`	basis-points	yes	Material readiness.
`method_option_key`	`string`	none	yes	Selected housing-method source identity.
`method_score`	`unsigned-integer`	basis-points	yes	Selected housing-method score.
`navigation_revision`	`revision`	none	yes	World navigation revision.
`neighboring_land_use`	`unsigned-integer`	basis-points	yes	Compatible neighboring settlement land.
`option_key`	`string`	none	yes	Stable composite parcel option identity.
`origin_x`	`signed-integer`	world-cells	yes	Exact footprint origin x.
`origin_y`	`signed-integer`	world-cells	yes	Exact footprint origin y.
`policy_key`	`string`	none	yes	Data-authored housing policy identity.
`pressure`	`unsigned-integer`	basis-points	yes	Current housing pressure.
`rejection`	`enumeration`	none	yes	Direct policy or portfolio result.
`resource_revision`	`revision`	none	yes	Resource revision assessed.
`risk`	`unsigned-integer`	basis-points	yes	Housing-method risk.
`score`	`signed-integer`	basis-points	yes	Weighted parcel score.
`selected`	`boolean`	none	yes	Whether this is the selected settlement parcel.
`service_access`	`unsigned-integer`	basis-points	yes	Nearby road-service access.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`source_method_evaluation_tick`	`unsigned-integer`	fixed-ticks	yes	Housing-method evaluation used.
`source_settlement_revision`	`revision`	none	yes	Settlement revision assessed.
`travel_efficiency`	`unsigned-integer`	basis-points	yes	Inverse travel cost.
`work_revision`	`revision`	none	yes	Work revision assessed.
`world_revision`	`revision`	none	yes	Combined World evidence revision.

Errors

Examples

local parcels = world.query("world.settlement.housing-parcels", {filters = {settlement_id = 1}, page_size = 16})
for _, parcel in ipairs(parcels.records) do
    ui.text(parcel.option_key, parcel.rejection .. ": " .. parcel.detail)
end

API history

1.19.0: Bounded World parcel alternatives, complete spatial evidence, stable settlement-wide selection, and direct rejection reasons added for Phase 19Q5C2B.