query · world.settlement

Settlement needs

Returns the latest retained settlement needs, forecasts, severity, evidence count, and direct reason for one settlement.

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

Stable ID: world.settlement.needs
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 food, water, fuel, housing, storage, labor, maintenance, and development assessment without creating a goal or changing a gameplay owner. Supply settlement_id to select the settlement.

Parameters

filters.settlement_id: required stable Settlement identity.
cursor: optional continuation cursor over needs in stable domain order.
page_size: bounded need-row limit.

Returns

Detached need rows with the current and source Settlement revisions, assessment cadence, typed domain and unit, current, target, and projected quantities, severity, trend, confidence, horizon, retained evidence count, and direct measured reason.

Cost

One exact Settlement lookup plus one bounded traversal of the latest retained need assessment page. Recurring assessment uses the settlement definition's rotating visit budget and fixed cadence.

Fields

ID	Type	Units	Required	Description
`assessment_tick`	`unsigned-integer`	fixed-ticks	yes	Fixed tick assessed.
`completed_assessment_count`	`unsigned-integer`	none	yes	Durable assessment sequence count.
`confidence`	`unsigned-integer`	basis-points	yes	Forecast confidence.
`current_quantity`	`unsigned-integer`	none	yes	Current measured quantity.
`domain`	`enumeration`	none	yes	Typed settlement need domain.
`horizon_ticks`	`unsigned-integer`	fixed-ticks	yes	Forecast horizon.
`next_assessment_tick`	`unsigned-integer`	fixed-ticks	yes	Next fixed tick when assessment may run.
`projected_quantity`	`unsigned-integer`	none	yes	Quantity forecast at the configured horizon.
`reason`	`string`	none	yes	Direct measured explanation.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`severity`	`unsigned-integer`	basis-points	yes	Shortfall severity.
`source_count`	`unsigned-integer`	none	yes	Owner evidence stamps retained.
`source_settlement_revision`	`revision`	none	yes	Settlement revision used to compose the assessment.
`target_quantity`	`unsigned-integer`	none	yes	Data-authored target quantity.
`trend`	`enumeration`	none	yes	Improving, stable, or worsening forecast.
`unit`	`enumeration`	none	yes	Quantity unit for current and target values.

Errors

Examples

local needs = world.query("world.settlement.needs", {filters = {settlement_id = 1}, page_size = 8})

API history

1.19.0: Settlement-owned dynamic need forecasts and causal evidence added for Phase 19Q1.