query · world.settlement

Household housing pressure

Returns the latest Settlement-owned housing pressure for each assessed household, including current and forecast capacity, condition, privacy, access, wealth, owner revisions, and direct reason.

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

Stable ID: world.settlement.housing-pressure
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

Read the latest Settlement-owned housing pressure for every assessed Household without selecting a repair, extension, shared residence, new building, or parcel. Supply settlement_id and optionally household_id to narrow the detached page.

Parameters

filters.settlement_id: required stable Settlement identity.
filters.household_id: optional stable Household identity.
cursor: optional continuation cursor over households in stable identity order.
page_size: bounded household-row limit.

Returns

Detached Household rows with current and forecast membership, residence, capacity, occupancy, sharing, condition, privacy, route access, wealth, six causal pressure components, weighted severity, status, confidence, direct reason, assessment cadence, and exact source-owner revisions.

Cost

One exact Settlement lookup plus one bounded traversal of the latest retained housing assessment. Recurring assessment uses the data-authored rotating Household visit budget and normal need cadence.

Fields

ID	Type	Units	Required	Description
`access_cost_ticks`	`unsigned-integer`	fixed-ticks	yes	Route cost between settlement anchor and residence.
`access_pressure`	`unsigned-integer`	basis-points	yes	Route access pressure.
`access_reachable`	`boolean`	none	yes	Whether the residence route is reachable.
`actor_revision`	`revision`	none	yes	Highest Actor revision assessed.
`assessed_at_tick`	`unsigned-integer`	fixed-ticks	yes	Household evidence tick.
`assessment_tick`	`unsigned-integer`	fixed-ticks	yes	Fixed tick assessed.
`building_condition`	`unsigned-integer`	basis-points	yes	Residence condition.
`building_revision`	`revision-or-null`	none	no	Residence revision assessed.
`completed_assessment_count`	`unsigned-integer`	none	yes	Durable settlement assessment sequence count.
`condition_pressure`	`unsigned-integer`	basis-points	yes	Building-condition pressure.
`confidence`	`unsigned-integer`	basis-points	yes	Assessment confidence.
`crowding_pressure`	`unsigned-integer`	basis-points	yes	Capacity shortfall pressure.
`current_dependents`	`unsigned-integer`	none	yes	Current dependent members.
`current_members`	`unsigned-integer`	none	yes	Current Household members.
`dependent_pressure`	`unsigned-integer`	basis-points	yes	Forecast-dependent pressure.
`expected_dependents`	`unsigned-integer`	none	yes	Additional dependents included in the housing forecast.
`household_id`	`stable-id`	none	yes	Assessed Household identity.
`household_revision`	`revision`	none	yes	Household revision assessed.
`household_wealth`	`unsigned-integer`	minor-currency-units	yes	Current household currency balance.
`next_assessment_tick`	`unsigned-integer`	fixed-ticks	yes	Next fixed tick when housing pressure may be reassessed.
`privacy`	`unsigned-integer`	basis-points	yes	Current household privacy.
`privacy_pressure`	`unsigned-integer`	basis-points	yes	Shared-residence privacy pressure.
`reason`	`string`	none	yes	Direct strongest housing-pressure reason.
`relationship_revision`	`revision`	none	yes	Highest Relationship revision assessed.
`required_capacity`	`unsigned-integer`	none	yes	Private capacity required by current and forecast members.
`residence_building_id`	`stable-id-or-null`	none	no	Current residence Building identity.
`residence_capacity`	`unsigned-integer`	none	yes	Current residence capacity.
`residence_occupants`	`unsigned-integer`	none	yes	All current occupants of the residence.
`resource_revision`	`revision`	none	yes	Highest Resource revision assessed.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`severity`	`unsigned-integer`	basis-points	yes	Weighted housing-pressure severity.
`sharing_households`	`unsigned-integer`	none	yes	Households sharing the current residence.
`source_settlement_revision`	`revision`	none	yes	Settlement revision used to compose the assessment.
`status`	`enumeration`	none	yes	Adequate, strained, or critical pressure.
`trend`	`enumeration`	none	yes	Improving, stable, or worsening pressure.
`wealth_pressure`	`unsigned-integer`	basis-points	yes	Household reserve pressure.
`wealth_target`	`unsigned-integer`	minor-currency-units	yes	Configured household wealth reserve.
`world_revision`	`revision`	none	yes	World revision assessed.

Errors

Examples

local housing = world.query("world.settlement.housing-pressure", {filters = {settlement_id = 1}, page_size = 16})
for _, household in ipairs(housing.records) do
    ui.text(tostring(household.household_id), household.status .. ": " .. household.reason)
end

API history

1.19.0: Household-specific current and forecast housing pressure, causal components, and owner revision evidence added for Phase 19Q5A.