query · world.settlement

Settlement economy

Returns one detached summary of the village's current production, pay, household market, and regional delivery state.

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

Stable ID: world.settlement.economy
Owner: game.production, game.trade, game.resource-economy, and game.household
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.13.0

Usage

Read the current authored production and trade opportunities, completed cycle counts, waits, pay, household purchase, merchant shipment, and delivered stock from their gameplay owners for the normal village interface.

Parameters

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

Returns

One detached economy row with authored opportunity keys, current stages and workers, completed cycle counts, known waits, wage and purchase completion, household output quantity, destination Site, and delivered trade quantity.

Cost

One bounded Production order traversal, Trade shipment traversal, Resource container traversal, and custody-transfer traversal.

Fields

ID	Type	Units	Required	Description
`completed_production_cycles`	`unsigned-integer`	none	yes	Completed production cycles retained by Production.
`completed_trade_cycles`	`unsigned-integer`	none	yes	Completed trade cycles retained by Trade.
`delivered_trade_quantity`	`unsigned-integer`	resource-units	yes	Authored trade resource held at its destination.
`household_output_quantity`	`unsigned-integer`	resource-units	yes	Current recipe output held by household goods inventories.
`household_purchase_completed`	`boolean`	none	yes	Whether a household completed a goods purchase.
`merchant_actor_id`	`stable-id-or-null`	none	no	Merchant leading the shipment when present.
`production_blockage`	`string-or-null`	none	no	Reason the current production cycle is waiting when known.
`production_opportunity_key`	`string-or-null`	none	no	Authored production opportunity being summarized.
`production_stage`	`enumeration`	none	yes	Current production stage.
`production_worker_id`	`stable-id-or-null`	none	no	Assigned worker on the current production cycle when present.
`trade_blockage`	`string-or-null`	none	no	Reason the current trade cycle is waiting when known.
`trade_destination_site_id`	`stable-id-or-null`	none	no	Shipment destination Site when present.
`trade_opportunity_key`	`string-or-null`	none	no	Authored trade opportunity being summarized.
`trade_stage`	`enumeration`	none	yes	Current regional shipment stage.
`wage_paid`	`boolean`	none	yes	Whether a production wage was paid.

Errors

Examples

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

API history

1.13.0: Live starter-village production, pay, household purchase, and merchant delivery summary added for Village Life addendum G.
1.16.0: Authored opportunity keys, recurring cycle counts, generic output quantities, and current blockage explanations added for Village Life addendum J.