query · world.settlement

Settlement spatial options

Returns the latest Settlement-owned spatial service portfolio, including current coverage, every facility, field, or connection alternative, exact parcel or anchor evidence, selection, score, and direct rejection reason.

world.settlement.spatial-options(filters?, cursor?, page_size?) -> query-page

Stable ID: world.settlement.spatial-options
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.19.0

Usage

Inspect the latest Settlement-owned comparison of current road, water, storage, field, workshop, and public-space alternatives. Supply settlement_id. The query reports the exact current evidence but cannot select a site or start physical work.

Parameters

filters.settlement_id: required stable Settlement identity.
cursor: optional continuation cursor over stable option identities.
page_size: bounded option-row limit.

Returns

Detached option rows with portfolio cadence and counters, service and method identity, facility definition, optional road anchors, optional land area and parcel origin, source revisions, population and service capacity, materials, labor, competing work, travel, risk, score, selection or direct rejection, and explanation.

Cost

One exact Settlement lookup plus one bounded traversal of the latest retained spatial portfolio. Runtime evaluation uses separately authored World-search, candidate, district, and mutation budgets.

Fields

ID	Type	Units	Required	Description
`active_competing_work_count`	`unsigned-integer`	none	yes	Current competing physical work.
`available_material_units`	`unsigned-integer`	none	yes	Available unreserved material.
`building_definition_id`	`string`	none	yes	Facility definition, or empty for roads and fields.
`candidate_visits`	`unsigned-integer`	none	yes	Complete alternatives visited.
`current_capacity`	`unsigned-integer`	none	yes	Current service capacity.
`detail`	`string`	none	yes	Direct selection or rejection explanation.
`eligible_candidate_count`	`unsigned-integer`	none	yes	Feasible alternatives before portfolio selection.
`eligible_labor_count`	`unsigned-integer`	none	yes	Current eligible labor.
`evaluation_tick`	`unsigned-integer`	fixed-ticks	yes	Fixed tick evaluated.
`first_anchor_id`	`stable-id-or-null`	none	no	First connection anchor identity.
`first_anchor_kind`	`enumeration-or-null`	none	no	First connection anchor kind.
`first_anchor_x`	`signed-integer-or-null`	world-cells	no	First anchor cell x.
`first_anchor_y`	`signed-integer-or-null`	world-cells	no	First anchor cell y.
`goal_key`	`string`	none	yes	Committed goal required by this spatial method.
`infrastructure_revision`	`revision`	none	yes	Infrastructure evidence revision.
`land_area_id`	`stable-id-or-null`	none	no	Candidate World land-area identity.
`maximum_travel_ticks`	`unsigned-integer`	fixed-ticks	yes	Authored travel limit.
`method_key`	`string`	none	yes	Data-authored spatial method identity.
`option_key`	`string`	none	yes	Stable spatial option identity.
`parcel_origin_x`	`signed-integer-or-null`	world-cells	no	Candidate facility origin x.
`parcel_origin_y`	`signed-integer-or-null`	world-cells	no	Candidate facility origin y.
`population`	`unsigned-integer`	none	yes	Population used for service demand.
`portfolio_detail`	`string`	none	yes	Direct portfolio result.
`rejection`	`enumeration`	none	yes	Direct feasibility or portfolio result.
`required_capacity`	`unsigned-integer`	none	yes	Required service capacity.
`required_material_units`	`unsigned-integer`	none	yes	Physical material requirement.
`resource_revision`	`revision`	none	yes	Resource evidence revision.
`risk`	`unsigned-integer`	basis-points	yes	Authored spatial risk.
`score`	`signed-integer`	basis-points	yes	Fixed-point portfolio score.
`second_anchor_id`	`stable-id-or-null`	none	no	Second connection anchor identity.
`second_anchor_kind`	`enumeration-or-null`	none	no	Second connection anchor kind.
`second_anchor_x`	`signed-integer-or-null`	world-cells	no	Second anchor cell x.
`second_anchor_y`	`signed-integer-or-null`	world-cells	no	Second anchor cell y.
`selected`	`boolean`	none	yes	Whether this option was selected.
`service`	`enumeration`	none	yes	Road, water, storage, field, workshop, or public-space service.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`source_settlement_revision`	`revision`	none	yes	Settlement revision used to evaluate the portfolio.
`travel_ticks`	`unsigned-integer`	fixed-ticks	yes	Current access travel.
`work_revision`	`revision`	none	yes	Work evidence revision.
`world_revision`	`revision`	none	yes	World evidence revision.

Errors

Examples

local options = world.query("world.settlement.spatial-options", {filters = {settlement_id = 1}, page_size = 32})
for _, option in ipairs(options.records) do
    ui.text(option.service, tostring(option.current_capacity) .. "/" .. tostring(option.required_capacity) .. ": " .. option.detail)
end

API history

1.19.0: Complete spatial service alternatives, physical location evidence, scores, selection, and direct rejection reasons added for Phase 19Q6E.