query · world.actor

Actor work status

Returns detached authored identity, health, plan, task, work stage, progress, and destination facts for one actor.

world.actor.status(filters?, cursor?, page_size?) -> query-page

Stable ID: world.actor.status
Owner: game.actor-runtime, game.settlement-supply, game.construction, and authored settlement
Authority: read_only
Timing: immediate
Availability: active-session
Side effects: none
Determinism: stable owner order at the current committed tick
Introduced: 1.3.0

Usage

Query one actor_id to inspect the villager's authored name and profession, injury, illness, impairment, recovery readiness, current plan and task, work stage and progress, and current source or destination without changing behavior.

Parameters

filters.actor_id: required stable Actor identity.
cursor: optional continuation cursor.
page_size: bounded record limit.

Returns

One detached worker-status record, or a stable unavailable result when the Actor is not embodied or loaded.

Cost

One Actor visit and bounded visits to the matching Supply or Construction owner.

Fields

ID	Type	Units	Required	Description
`actor_id`	`stable-id`	none	yes	Actor identity.
`destination_site_id`	`stable-id-or-null`	none	no	Current plan or work destination site.
`display_name`	`string`	none	yes	Authored display name or stable fallback label.
`illness`	`unsigned-integer`	basis-points	yes	Current illness severity.
`impairment`	`unsigned-integer`	basis-points	yes	Current physical impairment.
`injury`	`unsigned-integer`	basis-points	yes	Current injury severity.
`job_id`	`stable-id-or-null`	none	no	Current job identity.
`plan_change`	`enumeration`	none	yes	Reason for the latest plan change.
`plan_kind`	`enumeration`	none	yes	Current plan kind.
`plan_revision`	`unsigned-integer`	none	yes	Current plan revision.
`plan_status`	`enumeration`	none	yes	Current plan status.
`profession_definition_id`	`string-or-null`	none	no	Authored profession identity when the scenario supplies one.
`profession_display_name`	`string-or-null`	none	no	Player-facing authored profession name.
`recovery_ready`	`boolean`	none	yes	Whether retained injury recovery is ready.
`source_site_id`	`stable-id-or-null`	none	no	Current work source site.
`target_x_meters`	`number-or-null`	meters	no	Exact local destination X coordinate.
`target_y_meters`	`number-or-null`	meters	no	Exact local destination Y coordinate.
`task_kind`	`enumeration`	none	yes	Current task kind.
`task_progress`	`unsigned-integer`	basis-points	yes	Current task progress.
`task_status`	`enumeration`	none	yes	Current task status.
`work_kind`	`enumeration`	none	yes	Current supply, construction, or no work.
`work_progress`	`unsigned-integer`	basis-points	yes	Current domain work progress.
`work_stage`	`enumeration`	none	yes	Current domain-owned work stage.
`work_task_id`	`stable-id-or-null`	none	no	Current work-task identity.

Errors

Examples

local result = world.query("world.actor.status", {page_size = 1, filters = {actor_id = selected_id}})

API history

1.3.0: Detached villager work status added for Phase 16D.
1.8.0: Injury, illness, impairment, and recovery readiness added for Phase 17B.
1.9.0: Authored profession identity and display name added for the village interface.