query · world.settlement

Settlement production options

Returns the latest Settlement-owned production alternatives, physical feasibility, scores, selection, and exact Production owner bindings.

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

Stable ID: world.settlement.production-options
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 production alternatives considered during its latest strategy evaluation. The query is detached and cannot create, claim, advance, or cancel Production or Work.

Parameters

filters.settlement_id: required stable Settlement identity.
cursor: optional continuation cursor over options in stable policy-key order.
page_size: bounded option-row limit.

Returns

Detached option rows with decision cadence and budget counts; recipe, building, material source, output, quantity, eligible labor, condition, capacity, route, goal-support, and active direct-supply evidence; deterministic score and rejection; selection; and the exact Production order identity and revision when bound.

Cost

One exact Settlement lookup plus one bounded traversal of the latest retained production-option page. Recurring composition uses authored opportunity, selection, and cadence budgets and reads only current owner facts.

Fields

ID	Type	Units	Required	Description
`active_direct_supply_count`	`unsigned-integer`	none	yes	Active direct Supply commitments for the same need.
`available_input_quantity`	`unsigned-integer`	none	yes	Usable input quantity.
`available_service_capacity`	`unsigned-integer`	none	yes	Unreserved capacity.
`building_condition`	`unsigned-integer`	basis-points	yes	Observed condition.
`building_definition_id`	`string`	none	yes	Building definition identity.
`building_id`	`stable-id-or-null`	none	no	Observed building identity.
`building_revision`	`revision-or-null`	none	no	Observed building revision.
`candidate_visit_count`	`unsigned-integer`	none	yes	Alternatives visited.
`current_output_quantity`	`unsigned-integer`	none	yes	Current household output.
`detail`	`string`	none	yes	Direct selection or rejection explanation.
`eligible_candidate_count`	`unsigned-integer`	none	yes	Feasible alternatives.
`eligible_labor_count`	`unsigned-integer`	none	yes	Living adult settlement labor observed for the strategy horizon.
`evaluation_tick`	`unsigned-integer`	fixed-ticks	yes	Fixed tick evaluated.
`goal_support`	`unsigned-integer`	basis-points	yes	Active plan support.
`output_resource_id`	`stable-id`	none	yes	Output resource identity.
`policy_key`	`string`	none	yes	Data-authored production opportunity identity.
`production_order_id`	`stable-id-or-null`	none	no	Bound Production order.
`production_order_revision`	`revision-or-null`	none	no	Bound order revision.
`recipe_definition_id`	`string`	none	yes	Recipe definition identity.
`rejection`	`enumeration`	none	yes	Direct ineligibility reason or none.
`required_input_quantity`	`unsigned-integer`	none	yes	Required input quantity.
`required_service_capacity`	`unsigned-integer`	none	yes	Recipe capacity need.
`route_cost_ticks`	`unsigned-integer`	fixed-ticks	yes	Observed route cost.
`score`	`signed-integer`	basis-points	yes	Deterministic option score.
`selected`	`boolean`	none	yes	Whether Settlement selected this option.
`selected_candidate_count`	`unsigned-integer`	none	yes	Selected alternatives.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`source_container_id`	`stable-id-or-null`	none	no	Material source identity.
`source_revision`	`revision-or-null`	none	no	Material source revision.
`source_settlement_revision`	`revision`	none	yes	Settlement revision used to compose the decision.
`target_output_quantity`	`unsigned-integer`	none	yes	Authored output target.
`tuning_version`	`unsigned-integer`	none	yes	Fixed-point production reasoner tuning version.

Errors

Examples

local options = world.query("world.settlement.production-options", {filters = {settlement_id = 1}, page_size = 16})

API history

1.19.0: Dynamic production alternatives, direct feasibility evidence, cross-portfolio supply coordination, and exact Production bindings added for Phase 19Q4B1.