query · world.construction

Active construction

Returns a bounded stable-ID window of current construction projects.

world.construction.active(filters?, cursor?, page_size?) -> query-page

Stable ID: world.construction.active
Owner: game.construction
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.5.0

Usage

Read current active construction records, including worker-interruption blockage, recovery timing, and successful handoff history, before presenting status or submitting cancellation. Returned records are detached and cannot change the project.

Parameters

cursor: optional continuation cursor.
page_size: bounded active-project count.

Returns

Active Construction identities, definitions, Work revisions and player priority, stages, blockage, interruption timing, successful handoff history, and failure cause in stable order.

Cost

Bounded active Construction index visits.

Fields

ID	Type	Units	Required	Description
`blockage`	`enumeration`	none	yes	Current blockage reason.
`blocked_since_tick`	`unsigned-integer-or-null`	fixed-ticks	no	Tick when the current blockage began.
`construction_id`	`stable-id`	none	yes	Construction identity.
`definition_id`	`string`	none	yes	Authored building definition identity.
`failure_cause`	`enumeration`	none	yes	Retained terminal failure cause.
`job_id`	`stable-id`	none	yes	Construction Work job identity.
`job_revision`	`revision`	none	yes	Current Work job revision.
`last_worker_interruption_tick`	`unsigned-integer-or-null`	fixed-ticks	no	Most recent retained worker-interruption tick.
`last_worker_reassignment_tick`	`unsigned-integer-or-null`	fixed-ticks	no	Most recent successful worker-handoff tick.
`origin_x`	`signed-integer`	grid-cells	yes	Construction origin X coordinate.
`origin_y`	`signed-integer`	grid-cells	yes	Construction origin Y coordinate.
`player_priority`	`unsigned-integer`	basis-points	yes	Durable player-priority contribution.
`revision`	`revision`	none	yes	Current construction revision.
`stage`	`enumeration`	none	yes	Current construction stage.
`worker_handoff_count`	`unsigned-integer`	none	yes	Successful worker handoffs retained by Construction.
`worker_interruption_deadline_tick`	`unsigned-integer-or-null`	fixed-ticks	no	Tick when the worker-interruption recovery window expires.
`worker_interruption_grace_ticks_remaining`	`unsigned-integer-or-null`	fixed-ticks	no	Recovery ticks remaining before worker-interruption failure.

Errors

Examples

local active = world.query("world.construction.active", {page_size = 16})

API history

1.5.0: Active construction query added for Phase 16D.
1.5.0: Added worker-interruption recovery timing, successful handoff history, and failure cause for Phase 16F.
1.9.0: Current Work player priority added for the normal village focus.