query · world.actor

Actor routine

Returns one Actor's retained expected activity, actual choice, and reason.

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

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

Usage

Query one actor_id to read that resident's expected daily activity, current choice, and retained reason without requiring an embodied position. The result is detached and does not start, pause, or claim work.

Parameters

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

Returns

One detached routine record with the profile and routine revisions, expected and actual activities, decision reason, calendar position, completed day boundaries, deviation count, and whether the resident currently accepts new work.

Cost

One indexed Actor lookup within the package query budget; no population scan or simulation mutation.

Fields

ID	Type	Units	Required	Description
`accepts_new_work`	`boolean`	none	yes	Whether the current routine choice permits a new autonomous work claim.
`actor_id`	`stable-id`	none	yes	Actor identity.
`actual_activity`	`enumeration`	none	yes	Activity currently chosen by the Actor.
`calendar_day`	`unsigned-integer`	days	yes	Day evaluated by the Actor.
`completed_day_boundaries`	`unsigned-integer`	none	yes	Day boundaries crossed through hot or compressed visits.
`deviations`	`unsigned-integer`	none	yes	Retained count of off-schedule choices.
`evaluated_at_tick`	`unsigned-integer`	ticks	yes	Last bounded routine visit.
`minute_of_day`	`unsigned-integer`	minutes	yes	Clock minute evaluated by the Actor.
`planned_activity`	`enumeration`	none	yes	Activity expected by the daily schedule.
`profile_version`	`unsigned-integer`	none	yes	Routine profile generator version.
`reason`	`enumeration`	none	yes	Reason for the current choice.
`routine_revision`	`revision`	none	yes	Actor-owned routine revision.
`schedule_offset_minutes`	`signed-integer`	minutes	yes	Actor's stable personal timing offset from the authored routine.

Errors

Examples

local result = world.query("world.actor.routine", {page_size = 1, filters = {actor_id = actor_id}})
if result.status == "completed" then
    local routine = result.records[1]
    ui.row("Routine", routine.actual_activity)
    ui.row("Expected", routine.planned_activity)
end

API history

1.6.0: Detached resident routine and deviation evidence added for Phase 17A.