query · world.land

World land areas

Returns stable cell rows for World-owned irregular land areas and their retained condition.

world.land.areas(filters?, cursor?, page_size?) -> query-page

Stable ID: world.land.areas
Owner: sim.world
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

Read stable cell rows from World-owned irregular land areas. Each row repeats the area's validated land-use identity, retained condition, crop lifecycle, revision, and causal ticks without changing land. Active crop rows also expose physical work, forecast, recurring-cycle, worker-choice, replant, and blockage facts retained by Farming.

Parameters

filters.area_id: optional positive stable land-area identity.
cursor: optional continuation cursor returned by the same query.
page_size: positive record limit capped by the host.

Returns

A detached page containing one row per retained area cell in stable area and cell order, with area identity, total cell count, land use, condition, optional crop, lifecycle stage, revision, and causal ticks.

Cost

Bounded by page size and the package query and owner-visit budgets; the detached World area snapshot is scanned in canonical order.

Fields

ID	Type	Units	Required	Description
`area_id`	`stable-id`	none	yes	World land area identity.
`cell_count`	`unsigned-integer`	none	yes	Connected cells in the area.
`cell_x`	`signed-integer`	grid-cells	yes	World-grid cell X coordinate.
`cell_y`	`signed-integer`	grid-cells	yes	World-grid cell Y coordinate.
`controlling_site_id`	`stable-id-or-null`	none	no	Site currently controlling the area, independent of its dedication.
`conversion_stage`	`enumeration-or-null`	none	no	Current retained physical conversion stage.
`conversion_work_completed`	`unsigned-integer-or-null`	work-units	no	Work retained in the current conversion stage.
`conversion_work_required`	`unsigned-integer-or-null`	work-units	no	Work required by the current conversion stage.
`conversion_worker_id`	`stable-id-or-null`	none	no	Resident currently committed to conversion work.
`cover`	`enumeration`	none	yes	Current retained land cover.
`created_at_tick`	`unsigned-integer`	ticks	yes	Area creation tick.
`crop_definition_id`	`string-or-null`	none	no	Current crop identity.
`dedicated_site_id`	`stable-id-or-null`	none	no	Settlement site responsible for the dedicated area.
`dedication`	`enumeration`	none	yes	Current whole-area land dedication.
`depletion`	`unsigned-integer`	basis-points	yes	Current retained depletion.
`farming_blockage_reason`	`string-or-null`	none	no	Direct reason current settlement food need cannot advance this area.
`farming_choice_reason`	`string-or-null`	none	no	Direct reason for the latest crop, area, and resident choice.
`farming_completed_cycles`	`unsigned-integer-or-null`	cycles	no	Completed harvest or recovery cycles retained for this area.
`farming_forecast_reason`	`string-or-null`	none	no	Direct explanation for the latest crop forecast or outcome.
`farming_forecast_yield`	`unsigned-integer-or-null`	basis-points	no	Latest deterministic crop yield forecast.
`farming_growth_ready_tick`	`unsigned-integer-or-null`	ticks	no	Tick when the current growth interval can advance.
`farming_last_worker_id`	`stable-id-or-null`	none	no	Last resident selected for this crop cycle.
`farming_next_replant_tick`	`unsigned-integer-or-null`	ticks	no	Tick when retained land becomes eligible for another crop cycle.
`farming_outcome`	`enumeration-or-null`	none	no	Latest retained crop forecast or outcome.
`farming_stage`	`enumeration-or-null`	none	no	Current retained crop-cycle stage.
`farming_work_completed`	`unsigned-integer-or-null`	work-units	no	Work retained in the current crop stage.
`farming_work_required`	`unsigned-integer-or-null`	work-units	no	Work required by the current crop stage.
`farming_worker_id`	`stable-id-or-null`	none	no	Resident currently committed to crop work.
`fertility`	`unsigned-integer`	basis-points	yes	Current fertility.
`land_use_definition_id`	`string`	none	yes	Validated immutable land-use identity.
`lifecycle_stage`	`enumeration`	none	yes	Current crop or fallow lifecycle stage.
`moisture`	`unsigned-integer`	basis-points	yes	Current moisture.
`preferred_access`	`boolean`	none	yes	Whether this cell is a preferred gate or road access cell.
`preferred_access_count`	`unsigned-integer`	none	yes	Preferred access cells retained for the whole area.
`preparation`	`enumeration`	none	yes	Current retained preparation state.
`revision`	`revision`	none	yes	World land area revision.
`stage_started_at_tick`	`unsigned-integer`	ticks	yes	Current lifecycle-stage start tick.
`updated_at_tick`	`unsigned-integer`	ticks	yes	Latest area mutation tick.

Errors

Examples

local result = world.query("world.land.areas", {page_size = 32})
if result.status == "completed" then
    for _, cell in ipairs(result.records) do
        ui.row("Land " .. tostring(cell.area_id), cell.land_use_definition_id .. " / " .. cell.lifecycle_stage)
    end
end

API history

1.19.0: Detached irregular World land cells and retained crop lifecycle added for Village Life L1.