query · world.settlement

Settlement plans

Returns Settlement-owned dependency plans, requirement state, prerequisite count, and exact authoritative owner bindings.

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

Stable ID: world.settlement.plans
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 dependency plans that connect committed goals to current land, Resource, Production, Work, Infrastructure, Construction, and Building facts. The query is detached and cannot advance or cancel a requirement.

Parameters

filters.settlement_id: required stable Settlement identity.
cursor: optional continuation cursor over requirements in stable plan and requirement order.
page_size: bounded requirement-row limit.

Returns

Detached requirement rows with stable plan, goal, method, and requirement identities; plan and requirement status; dependency and alternative metadata; authored target; direct reason; and the exact authoritative owner binding when one exists.

Cost

One exact Settlement lookup plus one bounded traversal of retained plans and requirements. Recurring planning and reconciliation use authored visit, dependency, mutation, history, and cadence budgets.

Fields

ID	Type	Units	Required	Description
`alternative_group`	`string`	none	yes	Alternative choice group or empty string.
`binding_kind`	`enumeration-or-null`	none	no	Bound authoritative owner kind.
`binding_owner_revision`	`revision-or-null`	none	no	Observed owner revision.
`binding_stable_id`	`stable-id-or-null`	none	no	Bound owner identity.
`detail`	`string`	none	yes	Direct state or blocker reason.
`goal_id`	`stable-id`	none	yes	Durable source goal identity.
`goal_key`	`string`	none	yes	Data-authored source goal identity.
`method_key`	`string`	none	yes	Data-authored planning method identity.
`plan_id`	`stable-id`	none	yes	Durable dependency plan identity.
`plan_revision`	`revision`	none	yes	Current dependency plan revision.
`plan_status`	`enumeration`	none	yes	Current dependency plan status.
`prerequisite_count`	`unsigned-integer`	none	yes	Number of prerequisite requirements.
`requirement_id`	`stable-id`	none	yes	Durable requirement identity.
`requirement_key`	`string`	none	yes	Data-authored requirement identity.
`requirement_kind`	`enumeration`	none	yes	Domain owner required for execution.
`requirement_status`	`enumeration`	none	yes	Current requirement state.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`target_reference`	`string`	none	yes	Data-authored target reference.
`updated_at_tick`	`unsigned-integer`	fixed-ticks	yes	Last requirement update tick.

Errors

Examples

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

API history

1.19.0: Settlement-owned dependency plans and authoritative execution bindings added for Phase 19Q3.