query · world.settlement

Settlement stored resources

Returns paginated detached quantities physically held in one Settlement's stockpiles.

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

Stable ID: world.settlement.resources
Owner: game.settlement, game.resource-economy, and assets.runtime-content-catalog
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.0.0

Usage

Query one settlement_id to read only the resources physically retained in that Settlement's owned stockpiles. Use these records for settlement-store panels; do not substitute world-wide totals.

Parameters

filters.settlement_id: required positive Settlement identity.
cursor: optional continuation cursor indexing stable Resource identity order.
page_size: positive record limit capped by the host.

Returns

Detached stored-resource rows containing Settlement and Resource identities, authored key and display name, total stockpile quantity, available quantity, and reserved quantity.

Cost

One bounded Settlement lookup, one visit per retained stockpile and stored resource amount, and one Resource lookup per returned row, all charged to the package query budget.

Fields

ID	Type	Units	Required	Description
`available`	`unsigned-integer`	resource-units	yes	Unreserved stockpile quantity.
`display_name`	`string`	none	yes	Player-facing authored resource name.
`key`	`string`	none	yes	Authored resource key.
`reserved`	`unsigned-integer`	resource-units	yes	Reserved stockpile quantity.
`resource_id`	`stable-id`	none	yes	Resource identity.
`settlement_id`	`stable-id`	none	yes	Settlement identity.
`total`	`unsigned-integer`	resource-units	yes	Quantity held in Settlement stockpiles.

Errors

Examples

local result = world.query("world.settlement.resources", {
    page_size = 16,
    filters = {settlement_id = settlement.settlement_id}
})
if result.status == "completed" then
    for _, resource in ipairs(result.records) do
        ui.row(resource.display_name, tostring(resource.total))
    end
end

API history

1.5.0: Added a Settlement-owned stockpile view for player-facing store panels.