query · world.settlement

Settlement supply options

Returns the latest Settlement-owned physical supply alternatives, direct rejection reasons, scores, selections, and exact Supply owner bindings.

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

Stable ID: world.settlement.supply-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 physical food, water, fuel, and development-material alternatives considered during its latest supply evaluation. The query is detached and cannot create, claim, or advance Supply or Work.

Parameters

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

Returns

Detached option rows with portfolio cadence and budget counts; demand, beneficiary, resource, container, and Site identities; observed quantity, capacity, route, danger, need, gap, relief, re-entry, urgency, and alert facts; deterministic score and rejection; selection; and the exact Supply identity and revision when bound.

Cost

One exact Settlement lookup plus one bounded traversal of the latest retained supply-option page. Recurring composition uses authored Settlement, source, candidate, mutation, history, and cadence budgets.

Fields

ID	Type	Units	Required	Description
`available_quantity`	`unsigned-integer`	none	yes	Available source quantity.
`beneficiary_id`	`stable-id-or-null`	none	no	Resident beneficiary for need supply.
`candidate_visit_count`	`unsigned-integer`	none	yes	Physical source alternatives visited by the bounded reasoner.
`completed_evaluation_count`	`unsigned-integer`	none	yes	Durable supply portfolio sequence count.
`consumption_quantity`	`unsigned-integer`	none	yes	Quantity consumed by one need-supply execution.
`destination_container_id`	`stable-id`	none	yes	Physical destination container identity.
`destination_free_quantity`	`unsigned-integer`	none	yes	Observed free destination capacity.
`destination_site_id`	`stable-id`	none	yes	Physical destination site identity.
`detail`	`string`	none	yes	Direct selection or rejection explanation.
`domain`	`enumeration`	none	yes	Settlement need domain.
`eligible_candidate_count`	`unsigned-integer`	none	yes	Alternatives that passed every hard eligibility gate.
`evaluation_tick`	`unsigned-integer`	fixed-ticks	yes	Fixed tick evaluated.
`job_urgency`	`unsigned-integer`	basis-points	yes	Material supply job urgency.
`need_reentry`	`unsigned-integer`	basis-points	yes	Need threshold that permits repeat execution.
`need_relief`	`unsigned-integer`	basis-points	yes	Need relief per execution.
`need_severity`	`unsigned-integer`	basis-points	yes	Current demand severity.
`next_evaluation_tick`	`unsigned-integer`	fixed-ticks	yes	Next fixed tick when evaluation may run.
`option_id`	`stable-id`	none	yes	Durable physical option identity.
`policy_key`	`string`	none	yes	Data-authored demand policy identity.
`purpose`	`enumeration`	none	yes	Food, water, or material execution purpose.
`rejection`	`enumeration`	none	yes	Direct ineligibility reason or none.
`requested_quantity`	`unsigned-integer`	none	yes	Requested transfer quantity.
`resource_id`	`stable-id`	none	yes	Resource owner identity.
`route_cost_ticks`	`unsigned-integer`	fixed-ticks	yes	Observed route cost.
`route_danger`	`unsigned-integer`	basis-points	yes	Observed route danger.
`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	Alternatives selected for normal Supply execution.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`settlement_revision`	`revision`	none	yes	Current Settlement owner revision.
`source_container_id`	`stable-id`	none	yes	Physical source container identity.
`source_need_assessment_tick`	`unsigned-integer`	fixed-ticks	yes	Need assessment used as source evidence.
`source_settlement_revision`	`revision`	none	yes	Settlement revision used to compose the portfolio.
`source_site_id`	`stable-id`	none	yes	Physical source site identity.
`stock_gap_quantity`	`unsigned-integer`	none	yes	Observed stock shortfall.
`supply_id`	`stable-id-or-null`	none	no	Bound Supply owner identity.
`supply_revision`	`revision-or-null`	none	no	Bound Supply owner revision.
`tuning_version`	`unsigned-integer`	none	yes	Fixed-point supply portfolio tuning version.
`unfilled_alert_after_ticks`	`unsigned-integer`	fixed-ticks	yes	Delay before an unfilled supply alerts.

Errors

Examples

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

API history

1.19.0: Dynamic physical supply alternatives, direct rejection evidence, and exact Supply bindings added for Phase 19Q4A.