query · world.landscape

World landscape features

Returns bounded World-owned landscape identities, cluster membership, placement, and stable variation inputs without exposing render frame choices as simulation truth.

world.landscape.features(filters?, cursor?, page_size?) -> query-page

Stable ID: world.landscape.features
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 retained World landscape placement and lifecycle in stable feature order. Current appearance, lifecycle policy, kind, stage, maturity, renewal, and harvest facts come from World state; the variation key remains only a repeatable input for derived presentation. The query grants no mutation, atlas, or frame-choice authority.

Parameters

filters.feature_id: optional positive stable World landscape feature identity.
cursor: optional stable feature-identity continuation cursor returned by the same query.
page_size: positive record limit capped by the host.

Returns

A detached page containing feature and cluster identities, current family and lifecycle-policy identities, kind, stage, maturity, renewal and harvest ticks, canonical cell, density, revisions, creation tick, and stable variation key.

Cost

Bounded by page size and package query and owner-visit budgets. World resumes from the stable feature identity cursor without activating cold chunks.

Fields

ID	Type	Units	Required	Description
`appearance_family_id`	`string`	none	yes	Current validated landscape appearance-family identity.
`cell_x`	`signed-integer`	grid-cells	yes	World-grid cell X coordinate.
`cell_y`	`signed-integer`	grid-cells	yes	World-grid cell Y coordinate.
`cluster_id`	`stable-id`	none	yes	World landscape cluster identity.
`cluster_revision`	`revision`	none	yes	World landscape cluster revision.
`created_at_tick`	`unsigned-integer`	ticks	yes	Cluster creation tick.
`density`	`unsigned-integer`	basis-points	yes	Authored cluster density.
`feature_id`	`stable-id`	none	yes	World landscape feature identity.
`feature_revision`	`revision`	none	yes	World landscape feature revision.
`kind`	`enumeration`	none	yes	Tree, bush, or rock.
`last_harvested_at_tick`	`unsigned-integer-or-null`	ticks	no	Most recent committed harvest tick.
`lifecycle_policy_id`	`string`	none	yes	Immutable lifecycle and yield policy identity.
`maturity`	`unsigned-integer`	basis-points	yes	Current feature maturity.
`regrowth_due_tick`	`unsigned-integer-or-null`	ticks	no	Causal regrowth eligibility tick when the harvested feature is renewable.
`stage`	`enumeration`	none	yes	Standing, stump, or cleared.
`variation_key`	`unsigned-integer`	none	yes	Stable derived input used to choose among validated appearance frames.

Errors

Examples

local result = world.query("world.landscape.features", {page_size = 32})
if result.status == "completed" then
    for _, feature in ipairs(result.records) do
        ui.row(feature.appearance_family_id, tostring(feature.cell_x) .. ", " .. tostring(feature.cell_y))
    end
end

API history

1.19.0: Retained cluster placement and deterministic appearance input query added for Village Life N1.
1.19.1: Lifecycle policy, kind, stage, maturity, renewal, and harvest facts added for Village Life N2.