query · world.construction

Construction progress

Returns detached physical work, assigned-Actor throughput, duration, and blockage facts for one construction project.

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

Stable ID: world.construction.progress
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.0.0

Usage

Query one construction identity to inspect authored work, deterministic fractional progress, the assigned Actor's rate modifier, effective throughput, estimated remaining fixed ticks, stage, blockage, worker-interruption recovery deadline, retained handoff history, and terminal failure cause. Values are detached and cannot mutate Construction or Actor owners.

Parameters

filters.construction_id: required stable construction identity.
cursor: optional continuation cursor; this single-record query normally returns none.
page_size: positive record limit capped by the host.

Returns

One detached construction record. Worker and rate-derived fields are null when no Actor is assigned. Interruption timing fields are null unless the project is blocked by a worker interruption.

Cost

One Construction lookup and, when a worker is assigned, one Actor lookup within package query budgets.

Fields

ID	Type	Units	Required	Description
`base_work_units_per_second`	`unsigned-integer`	work-units-per-second	yes	Current runtime base construction throughput.
`blockage`	`enumeration`	none	yes	Current blockage reason.
`blocked_since_tick`	`unsigned-integer-or-null`	fixed-ticks	no	Tick when the current blockage began.
`completed_work_units`	`unsigned-integer`	work-units	yes	Completed physical work.
`construction_id`	`stable-id`	none	yes	Construction identity.
`definition_id`	`string`	none	yes	Authored building definition identity.
`effective_work_units_per_second`	`number-or-null`	work-units-per-second	no	Derived base throughput after the assigned Actor modifier.
`estimated_remaining_ticks`	`unsigned-integer-or-null`	fixed-ticks	no	Derived fixed ticks remaining at the current rate.
`failure_cause`	`enumeration`	none	yes	Retained terminal failure cause.
`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.
`progress`	`unsigned-integer`	basis-points	yes	Derived completion ratio.
`required_work_units`	`unsigned-integer`	work-units	yes	Authored physical work required.
`stage`	`enumeration`	none	yes	Current construction stage.
`work_remainder_numerator`	`unsigned-integer`	construction-work-rate-numerator	yes	Retained deterministic fractional work numerator.
`worker_actor_id`	`stable-id-or-null`	none	no	Assigned construction Actor when present.
`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.
`worker_rate_modifier`	`unsigned-integer-or-null`	basis-points	no	Assigned Actor construction-rate modifier.

Errors

Examples

local result = world.query("world.construction.progress", {page_size = 1, filters = {construction_id = 1}})
if result.status == "completed" then
    local project = result.records[1]
    ui.row("Build work", tostring(project.completed_work_units) .. " / " .. tostring(project.required_work_units))
    if project.blockage == "worker_interrupted" then
        ui.row("Recovery window", tostring(project.worker_interruption_grace_ticks_remaining) .. " ticks")
    elseif project.failure_cause ~= "none" then
        ui.text("Construction failed", project.failure_cause)
    end
end

API history

1.0.0: Runtime contract published from the complete Phase 14 registry.
1.1.0: Replaced tick-named progress with physical work units, fractional remainder, Actor rate, and duration fields.
1.5.0: Added worker-interruption timing, successful handoff history, and retained failure cause for Phase 16F.