query · world.settlement

Village demography

Returns one detached summary of current population viability, retained life-course transitions, authored bounds, and the current growth blockage.

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

Stable ID: world.settlement.demography
Owner: assets.runtime-settlement-definition, game.actor-runtime, game.relationship, game.household, game.resource-economy, game.construction, 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.17.0

Usage

Read the retained settlement population trajectory, demographic gates, current population, labor, household, housing, food, health, safety, service, enterprise, prosperity, and life-event evidence without changing the settlement.

Parameters

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

Returns

One detached demographic row with the retained growing, stable, stagnating, declining, recovering, or abandoned trajectory; birth, immigration, and emigration decisions and reasons; current prosperity; population, labor, Household, housing, food, health, safety, service, enterprise, life-event, authored-limit, and visit-budget facts.

Cost

One exact retained Settlement strategy plus bounded Construction, Resource, Actor, Relationship, Household, Production, and Trade evidence; recurring demographic mutation remains limited by authored rotating visit and mutation budgets.

Fields

ID	Type	Units	Required	Description
`active_enterprises`	`unsigned-integer`	none	yes	Current active enterprise commitments.
`actor_visit_budget`	`unsigned-integer`	none	yes	Maximum Actors evaluated per demographic update.
`adult_labor`	`unsigned-integer`	basis-points	yes	Healthy adult share of residents.
`adult_labor_population`	`unsigned-integer`	none	yes	Healthy adult residents available to sustain labor.
`birth_allowed`	`boolean`	none	yes	Whether current strategy permits the existing birth path.
`birth_reason`	`string`	none	yes	Direct reason for the current birth gate.
`births`	`unsigned-integer`	none	yes	Retained Actor lineages created by birth.
`condition`	`enumeration`	none	yes	Retained growing, stable, stagnating, declining, recovering, or abandoned trajectory.
`deaths`	`unsigned-integer`	none	yes	Actors with retained death facts.
`emigrants`	`unsigned-integer`	none	yes	Actors with retained emigration facts.
`emigration_pressure`	`boolean`	none	yes	Whether current strategy pressures an eligible resident to leave.
`emigration_reason`	`string`	none	yes	Direct reason for the current emigration pressure.
`evaluation_interval_ticks`	`unsigned-integer`	ticks	yes	Authored demographic evaluation cadence.
`food_units`	`unsigned-integer`	resource-units	yes	Accessible demographic food reserve.
`growth_blockage`	`string-or-null`	none	no	Current settlement-level reason growth cannot proceed.
`health`	`unsigned-integer`	basis-points	yes	Current resident health support.
`household_count`	`unsigned-integer`	none	yes	Current Settlement Households.
`household_visit_budget`	`unsigned-integer`	none	yes	Maximum Households evaluated per demographic update.
`households_separated`	`unsigned-integer`	none	yes	Retained Household-owned separation formations.
`housing_capacity`	`unsigned-integer`	none	yes	Usable authored housing capacity.
`immigrants`	`unsigned-integer`	none	yes	Actors with retained immigration provenance.
`immigration_allowed`	`boolean`	none	yes	Whether current strategy permits the existing immigration path.
`immigration_population_ceiling`	`unsigned-integer`	none	yes	Authored ceiling for labor-driven immigration.
`immigration_reason`	`string`	none	yes	Direct reason for the current immigration gate.
`immigration_recovery_population`	`unsigned-integer`	none	yes	Authored population level restored by recovery immigration.
`maximum_population`	`unsigned-integer`	none	yes	Authored population ceiling.
`minimum_population`	`unsigned-integer`	none	yes	Authored population floor.
`mutation_budget`	`unsigned-integer`	none	yes	Maximum demographic mutations per update.
`partnerships_formed`	`unsigned-integer`	none	yes	Retained Relationship-owned partnership formations.
`population`	`unsigned-integer`	none	yes	Current living Settlement residents.
`population_pressure`	`boolean`	none	yes	Whether population, housing, food, or Household strain creates decline pressure.
`prosperity`	`enumeration`	none	yes	Current prosperity evidence used by strategy.
`recent_migration_change`	`signed-integer`	none	yes	Immigrants minus emigrants since the previous retained evaluation.
`recent_natural_change`	`signed-integer`	none	yes	Births minus deaths since the previous retained evaluation.
`relationship_visit_budget`	`unsigned-integer`	none	yes	Maximum Relationships evaluated per demographic update.
`required_food_units`	`unsigned-integer`	resource-units	yes	Food required for the current resident count.
`safety`	`unsigned-integer`	basis-points	yes	Current settlement safety support.
`selected_enterprises`	`unsigned-integer`	none	yes	Current selected enterprise opportunities.
`services`	`unsigned-integer`	basis-points	yes	Current operational service support.
`strained_households`	`unsigned-integer`	none	yes	Households above the authored demographic strain limit.
`target_population`	`unsigned-integer`	none	yes	Authored sustainable target.

Errors

Examples

local demography = world.query("world.settlement.demography", {page_size = 1})

API history

1.17.0: Authored recurring demography and current village viability summary added for Village Life addendum K.
1.19.0: Retained population trajectory, cross-owner evidence, and explicit demographic gates added for civilization autonomy Q8.