query · world.settlement

Village families

Returns current Household membership, life-stage counts, residence, and latest change together with physical pantry and domestic-work facts.

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

Stable ID: world.settlement.families
Owner: game.household, game.actor-runtime, game.resource-economy, game.settlement-supply, and game.settlement
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.11.0

Usage

Read current village households, their membership and life-stage counts, assigned residence, physical pantry reserve, strain, latest care, and latest domestic Work without changing family state.

Parameters

cursor: optional continuation cursor.
page_size: bounded household-row limit.

Returns

Detached Household rows in current Settlement order with child, adolescent, adult, elder, residence, pantry food, strain, latest care, latest domestic Work, reason, and update facts.

Cost

One Settlement lookup, one bounded Household lookup per row, one Actor lookup per retained member, one pantry traversal, and one bounded Supply traversal per Household.

Fields

ID	Type	Units	Required	Description
`adolescent_count`	`unsigned-integer`	none	yes	Current adolescent members.
`adult_count`	`unsigned-integer`	none	yes	Current adult members.
`child_count`	`unsigned-integer`	none	yes	Current child members.
`domestic_work_stage`	`enumeration-or-null`	none	no	Latest pantry-restocking Work stage.
`domestic_worker_id`	`stable-id-or-null`	none	no	Actor assigned to the latest pantry-restocking Work.
`elder_count`	`unsigned-integer`	none	yes	Current elder members.
`household_id`	`stable-id`	none	yes	Household identity.
`last_reason`	`enumeration`	none	yes	Latest Household change reason.
`latest_care_kind`	`enumeration-or-null`	none	no	Latest retained care activity.
`latest_care_tick`	`unsigned-integer-or-null`	ticks	no	Tick of the latest retained care activity.
`member_count`	`unsigned-integer`	none	yes	Current Household members.
`pantry_food_quantity`	`unsigned-integer`	none	yes	Food units physically held by the Household pantry.
`residence_building_id`	`stable-id-or-null`	none	no	Assigned residence.
`strain`	`unsigned-integer`	basis-points	yes	Current Household strain.
`updated_at_tick`	`unsigned-integer`	ticks	yes	Latest Household update.

Errors

Examples

local families = world.query("world.settlement.families", {page_size = 8})

API history

1.11.0: Current family and life-stage summary added for Village Life addendum E.
1.12.0: Physical pantry, Household strain, latest care, and domestic Work facts added for Village Life addendum F.
1.19.3: Adolescent Household counts added for Village Life O2.