query · world.settlement

Household housing methods

Returns Settlement-owned repair, extension, shared-residence, and new-construction options from the latest current facts, including feasibility, score, selection, cost, capacity, evidence revisions, and direct rejection reason.

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

Stable ID: world.settlement.housing-methods
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 Settlement-owned repair, extension, shared-residence, and new-construction alternatives composed from current Household, Building, Resource, Work, Relationship, and World facts. Supply settlement_id and optionally household_id. The query cannot select a parcel or start work.

Parameters

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

Returns

Detached option rows with method and policy identity, target Building or definition, pressure, capacity gain or deficit, condition recovery, compatibility, materials, labor, access, wealth, benefit, cost, risk, score, selection or direct rejection, and exact source revisions.

Cost

One exact Settlement lookup plus one bounded traversal of the current retained method ledger. Recurring comparison uses data-authored rotating Household and candidate visit budgets.

Fields

ID	Type	Units	Required	Description
`access_cost_ticks`	`unsigned-integer`	fixed-ticks	yes	Current route cost.
`available_material_units`	`unsigned-integer`	none	yes	Available required units.
`benefit`	`unsigned-integer`	basis-points	yes	Weighted benefit.
`building_definition_id`	`string`	none	yes	Target building definition.
`building_revision`	`revision-or-null`	none	no	Target Building revision.
`capacity_deficit`	`unsigned-integer`	none	yes	Unmet capacity.
`capacity_gain`	`unsigned-integer`	none	yes	Capacity this method could add.
`compatibility`	`unsigned-integer`	basis-points	yes	Shared-residence social compatibility.
`condition_recovery`	`unsigned-integer`	basis-points	yes	Condition this method could restore.
`cost`	`unsigned-integer`	basis-points	yes	Weighted scarcity cost.
`detail`	`string`	none	yes	Direct selection or rejection explanation.
`eligible_labor_count`	`unsigned-integer`	none	yes	Available adult workers.
`household_id`	`stable-id`	none	yes	Household considering the method.
`household_revision`	`revision`	none	yes	Household revision assessed.
`household_wealth`	`unsigned-integer`	minor-currency-units	yes	Current household wealth.
`material_source_id`	`stable-id-or-null`	none	no	Material stockpile.
`method`	`enumeration`	none	yes	Repair, extension, shared residence, or new construction.
`option_key`	`string`	none	yes	Stable option identity.
`policy_key`	`string`	none	yes	Data-authored method policy identity.
`pressure`	`unsigned-integer`	basis-points	yes	Current housing pressure.
`rejection`	`enumeration`	none	yes	Direct feasibility or portfolio result.
`required_material_units`	`unsigned-integer`	none	yes	Required material units.
`required_work_units`	`unsigned-integer`	none	yes	Required labor units.
`resource_revision`	`revision`	none	yes	Resource evidence revision.
`risk`	`unsigned-integer`	basis-points	yes	Authored method risk.
`score`	`signed-integer`	basis-points	yes	Weighted method score.
`selected`	`boolean`	none	yes	Whether this is the selected method.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`source_pressure_tick`	`unsigned-integer`	fixed-ticks	yes	Housing pressure evidence tick.
`source_settlement_revision`	`revision`	none	yes	Settlement revision assessed.
`target_building_id`	`stable-id-or-null`	none	no	Existing target Building.
`wealth_cost`	`unsigned-integer`	minor-currency-units	yes	Method wealth cost.
`work_revision`	`revision`	none	yes	Work evidence revision.
`world_revision`	`revision`	none	yes	World evidence revision.

Errors

Examples

local methods = world.query("world.settlement.housing-methods", {filters = {settlement_id = 1}, page_size = 16})
for _, option in ipairs(methods.records) do
    ui.text(option.method, option.detail)
end

API history

1.19.0: Bounded housing-method alternatives, current feasibility evidence, stable selection, and direct rejection reasons added for Phase 19Q5B.